/ Hex Artifact Content
Login

Artifact a51577ed847b75fff9c10b7ea35e37e8154cee71:


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 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  eter of.** sqlit
39c0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
39d0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
39e0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
39f0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3a00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3a10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3a30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3a40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3a50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3a60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3a70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3a80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3a90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3aa0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3ab0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3ac0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3ad0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3af0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3b00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3b10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3b20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3b30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3b40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3b50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3b60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3b70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3b80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3b90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3ba0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3bb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3bc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3bd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3be0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3bf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3c10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3c20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3c30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3c40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3c50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3c60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3c70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3c80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3c90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3ca0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3cb0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3cc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3cd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3ce0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3cf0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3d20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3d50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3d60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3d70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3d80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3d90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3da0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3db0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3dc0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3dd0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3de0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3df0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3e00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3e10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3e20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3e30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3e40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3e50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3e60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3e70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3e80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3e90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3ea0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3eb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3ec0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ed0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3ee0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
3ef0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
3f00: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3f10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3f20: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
3f30: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
3f40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
3f50: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3f60: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
3f70: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
3f80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3f90: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3fa0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3fb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3fc0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3fd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fe0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ff0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4000: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4010: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4020: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4030: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4040: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4050: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4060: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4070: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
4080: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
4090: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
40a0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
40d0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
40e0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
40f0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4120: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4130: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4140: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4150: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4160: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4170: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41a0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
41b0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
41c0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
41f0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4200: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4210: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4220: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4230: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4240: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4250: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4260: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4270: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
4280: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
4290: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
42a0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
42b0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
42c0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
42d0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
42e0: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
42f0: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4300: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4310: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4320: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4330: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4340: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4350: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4360: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4370: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4380: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4390: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43a0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
43b0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
43c0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
43d0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
43e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
43f0: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4400: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4410: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4420: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4430: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4440: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4450: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4470: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4480: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4490: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44a0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
44b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
44c0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
44d0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
44e0: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
44f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4500: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4510: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4520: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4530: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4540: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4550: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4560: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4580: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4590: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45a0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
45b0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
45c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
45d0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
45e0: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
45f0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4600: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4620: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4630: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4640: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4650: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4660: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4670: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4680: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4690: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46b0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
46c0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
46d0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
46e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
46f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4700: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4710: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4720: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4730: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4760: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4770: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4780: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4790: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47a0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
47b0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
47c0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
47d0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
47e0: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
47f0: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4810: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4820: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4830: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4840: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4850: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4860: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4870: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4880: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48a0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
48b0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
48c0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
48d0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
48e0: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
48f0: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4900: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4920: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4930: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4940: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4960: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4970: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4980: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4990: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
49b0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
49c0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
49d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
49e0: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
49f0: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a00: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a10: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a20: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a30: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a40: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4a50: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4a60: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a70: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a80: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a90: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4aa0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4ab0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4ad0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4ae0: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4af0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b10: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4b20: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4b30: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b50: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4b60: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4b70: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4b80: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4ba0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4bb0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4bc0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4bd0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4be0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4bf0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4c00: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4c10: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4c20: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4c30: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4c40: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4c50: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4c60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4c70: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4c80: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4c90: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4ca0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4cb0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4cc0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4cd0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4ce0: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4cf0: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4d00: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4d10: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4d20: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4d30: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4d40: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4d50: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4d60: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4d70: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4d80: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4d90: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4da0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
4db0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
4dc0: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
4dd0: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
4de0: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
4df0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
4e00: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
4e10: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
4e20: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
4e30: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
4e40: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4e50: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
4e60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4e70: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
4e80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4e90: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4ea0: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
4eb0: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
4ec0: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
4ed0: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
4ee0: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
4ef0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
4f00: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
4f10: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
4f20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4f30: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f50: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4f60: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4f70: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4f90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fa0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
4fb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
4fd0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4fe0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
4ff0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5000: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5010: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5020: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5030: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5040: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5050: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5060: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
5070: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5080: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
5090: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50a0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
50b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50c0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
50d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50e0: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
50f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5100: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5120: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5130: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5140: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5160: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
5170: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5180: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
5190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51a0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
51b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51c0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5220: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5230: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5240: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5260: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
5270: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
5280: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
5290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52a0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
52b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52c0: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
52d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52e0: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
52f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5300: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5320: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5330: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5340: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
5350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5360: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
5370: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5380: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
5390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53a0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
53b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53c0: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
53d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53e0: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
53f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5400: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5420: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5430: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5440: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
5450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5460: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
5470: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5480: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
5490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54a0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
54b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54c0: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
54d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54e0: 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20  ERR_MMAP        
54f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5500: 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23  ERR | (24<<8)).#
5510: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5520: 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20  ERR_GETTEMPPATH 
5530: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5540: 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23  ERR | (25<<8)).#
5550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5560: 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  ERR_CONVPATH    
5570: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5580: 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23  ERR | (26<<8)).#
5590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55a0: 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20  ERR_VNODE       
55b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
55c0: 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23  ERR | (27<<8)).#
55d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55e0: 45 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20  ERR_AUTH        
55f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5600: 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23  ERR | (28<<8)).#
5610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5620: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5630: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5640: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
5650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5660: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
5670: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5680: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
5690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56a0: 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20  BUSY_SNAPSHOT   
56b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56c0: 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29  BUSY   |  (2<<8)
56d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56e0: 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50  _CANTOPEN_NOTEMP
56f0: 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45  DIR      (SQLITE
5700: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c  _CANTOPEN | (1<<
5710: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5720: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49  TE_CANTOPEN_ISDI
5730: 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  R          (SQLI
5740: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32  TE_CANTOPEN | (2
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5760: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55  LITE_CANTOPEN_FU
5770: 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51  LLPATH       (SQ
5780: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5790: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
57a0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57b0: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28  CONVPATH       (
57c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
57d0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
57e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
57f0: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20  _VTAB           
5800: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5810: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5830: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5840: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5850: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5870: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5880: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5890: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
58a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
58b0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
58c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
58d0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
58e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58f0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5900: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5910: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5920: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5930: 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b  E_ABORT_ROLLBACK
5940: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5950: 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29  E_ABORT | (2<<8)
5960: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43  _CONSTRAINT_CHEC
5980: 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  K        (SQLITE
5990: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31  _CONSTRAINT | (1
59a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59c0: 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51  COMMITHOOK   (SQ
59d0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59e0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
59f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a00: 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20  INT_FOREIGNKEY  
5a10: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a20: 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  INT | (3<<8)).#d
5a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a40: 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e  STRAINT_FUNCTION
5a50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a60: 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29  STRAINT | (4<<8)
5a70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e  _CONSTRAINT_NOTN
5a90: 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45  ULL      (SQLITE
5aa0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35  _CONSTRAINT | (5
5ab0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5ad0: 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51  PRIMARYKEY   (SQ
5ae0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5af0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
5b00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5b10: 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20  INT_TRIGGER     
5b20: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5b30: 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  INT | (7<<8)).#d
5b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5b50: 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20  STRAINT_UNIQUE  
5b60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b70: 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29  STRAINT | (8<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42  _CONSTRAINT_VTAB
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39  _CONSTRAINT | (9
5bc0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5bd0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5be0: 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51  ROWID        (SQ
5bf0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5c00: 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e  |(10<<8)).#defin
5c10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c20: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
5c30: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c40: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5c50: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c60: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
5c70: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c80: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5c90: 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47  e SQLITE_WARNING
5ca0: 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20  _AUTOINDEX      
5cb0: 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47   (SQLITE_WARNING
5cc0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5cd0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55  ne SQLITE_AUTH_U
5ce0: 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20  SER             
5cf0: 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c    (SQLITE_AUTH |
5d00: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
5d10: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
5d20: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
5d30: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
5d40: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5d50: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
5d60: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
5d70: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
5d80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
5d90: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
5da0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
5db0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5dc0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
5dd0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
5de0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5df0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5e00: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5e10: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
5e20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5e40: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
5e50: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
5e60: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5e70: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5e90: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5ea0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5eb0: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5ec0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5ed0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5ee0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5ef0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5f00: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
5f10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5f20: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
5f30: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
5f40: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
5f50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5f60: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5f70: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5f80: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5f90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5fa0: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
5fb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5fc0: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
5fd0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5fe0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5ff0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
6000: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6010: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
6020: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6030: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6040: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6050: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6060: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6070: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6080: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6090: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
60a0: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
60b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
60c0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
60d0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
60e0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
60f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6100: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
6110: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
6120: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
6130: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6140: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6150: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6160: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6170: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6180: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6190: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
61a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
61b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
61c0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
61d0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
61e0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
61f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6200: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
6210: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
6220: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6230: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6240: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6250: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6260: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6270: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6280: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6290: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62a0: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
62b0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
62c0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
62d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
62e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62f0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
6300: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
6310: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6320: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6330: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6340: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6350: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6360: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6370: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
6380: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6390: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
63a0: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
63b0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
63c0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
63d0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
63e0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
63f0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
6400: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6410: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
6420: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
6430: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6440: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6450: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6460: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6470: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6480: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6490: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
64a0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
64b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
64c0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
64d0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
64e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
64f0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6500: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6510: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6520: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6530: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6540: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6550: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6560: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6570: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6580: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6590: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
65a0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
65b0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
65c0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
65d0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
65e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
65f0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6600: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6610: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6620: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6630: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6640: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6650: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6660: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6670: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6680: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6690: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
66a0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
66b0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
66c0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
66d0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
66e0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
66f0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6700: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6710: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6720: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6730: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6740: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6750: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6760: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6770: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6780: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6790: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
67a0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
67b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
67c0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
67d0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
67e0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
67f0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6800: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6810: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6820: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6830: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6840: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6850: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6860: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6870: 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  te that a file c
6880: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6890: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
68a0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
68b0: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
68c0: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
68d0: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
68e0: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
68f0: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6900: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6910: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6920: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6930: 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  eges..*/.#define
6940: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6950: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20  OMIC            
6960: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
6970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6980: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
6990: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
69a0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
69b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
69c0: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC1K            
69d0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
69e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69f0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
6a00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a10: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
6a20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6a30: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6a40: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
6a50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a60: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
6a70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6a80: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
6a90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6aa0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6ab0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
6ac0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6ad0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20  TOMIC32K        
6ae0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6af0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
6b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b20: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
6b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6b40: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20  E_APPEND        
6b50: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
6b60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b70: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
6b80: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b90: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
6ba0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6bb0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6bc0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
6bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6be0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6bf0: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31  WRITE    0x00001
6c00: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
6c10: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
6c20: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  LE              
6c30: 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a  0x00002000../*.*
6c40: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
6c50: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
6c60: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
6c70: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
6c80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6c90: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
6ca0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
6cb0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
6cc0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6cd0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
6ce0: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
6cf0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6d00: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
6d10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6d20: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
6d30: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6d40: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
6d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6d60: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
6d70: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
6d80: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
6d90: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
6da0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6db0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
6dc0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
6dd0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
6de0: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
6df0: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
6e00: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
6e10: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
6e20: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6e30: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
6e40: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
6e50: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
6e60: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6e70: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
6e80: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
6e90: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6ea0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
6eb0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
6ec0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
6ed0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
6ee0: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
6ef0: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
6f00: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
6f10: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
6f20: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
6f30: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6f40: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
6f50: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
6f60: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
6f70: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
6f80: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
6f90: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
6fa0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6fb0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
6fc0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6fd0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6fe0: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6ff0: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
7000: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
7010: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
7020: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
7030: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7040: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7050: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
7060: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
7070: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
7080: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
7090: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
70a0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
70b0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
70c0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
70d0: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
70e0: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
70f0: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
7100: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
7110: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
7120: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
7130: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7140: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7150: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
7160: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
7170: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
7180: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
7190: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
71a0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
71b0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
71c0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
71d0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
71e0: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
71f0: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
7200: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
7210: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
7220: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
7230: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
7240: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7250: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7260: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
7270: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
7280: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
7290: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
72a0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
72b0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
72c0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
72d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
72e0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
72f0: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
7300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7310: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
7320: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
7330: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7340: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
7350: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7360: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7370: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
7380: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
7390: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
73a0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
73b0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
73c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
73d0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
73e0: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
73f0: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
7400: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
7410: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
7420: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
7430: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
7440: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
7450: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
7460: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
7470: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
7480: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
7490: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
74a0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
74b0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
74c0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
74d0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
74e0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
74f0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
7500: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7510: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
7520: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
7530: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
7540: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
7550: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
7560: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
7570: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
7580: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
7590: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
75a0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
75b0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
75c0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
75d0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
75e0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
75f0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7600: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
7610: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7620: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
7630: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
7640: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
7650: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7660: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
7670: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
7680: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
7690: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
76a0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
76b0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
76c0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
76d0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
76e0: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
76f0: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
7700: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7710: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
7720: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
7730: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7740: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
7750: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7760: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7770: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
7780: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
7790: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
77a0: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
77b0: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
77c0: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
77d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
77e0: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
77f0: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
7800: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
7810: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
7820: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
7830: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
7840: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7850: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
7860: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7870: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7880: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7890: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
78a0: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
78b0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
78c0: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
78d0: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
78e0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
78f0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
7900: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
7910: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
7920: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
7930: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
7940: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
7950: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7960: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
7970: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
7980: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
7990: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
79a0: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
79b0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
79c0: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
79d0: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
79e0: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
79f0: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
7a00: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
7a10: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
7a20: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
7a30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7a40: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
7a50: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7a60: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
7a70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
7a80: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
7a90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7aa0: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
7ab0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7ac0: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
7ad0: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
7ae0: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
7af0: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
7b00: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7b10: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
7b20: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
7b30: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
7b40: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
7b50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
7b60: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
7b70: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
7b80: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
7b90: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
7ba0: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
7bb0: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
7bc0: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
7bd0: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
7be0: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
7bf0: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
7c00: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
7c10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
7c20: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
7c30: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
7c40: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
7c50: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
7c60: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7c70: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
7c80: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
7c90: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
7ca0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7cb0: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
7cc0: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
7cd0: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
7ce0: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
7cf0: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
7d00: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
7d10: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
7d20: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
7d30: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
7d40: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
7d50: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
7d60: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
7d70: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
7d80: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
7d90: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
7da0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7db0: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
7dc0: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
7dd0: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
7de0: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
7df0: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
7e00: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
7e10: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
7e20: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
7e30: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
7e40: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
7e50: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
7e60: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
7e70: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
7e80: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
7e90: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
7ea0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
7eb0: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
7ec0: 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ** A [file contr
7ed0: 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73  ol opcodes | lis
7ee0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7ef0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7f00: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7f10: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7f20: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
7f30: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7f40: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7f50: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7f60: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7f70: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7f80: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7f90: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7fa0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7fb0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7fc0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7fd0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7fe0: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7ff0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
8000: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
8010: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
8020: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
8030: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
8040: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
8050: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
8060: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
8070: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
8080: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
8090: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
80a0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
80b0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
80c0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
80d0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
80e0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
80f0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
8100: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
8110: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
8120: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
8130: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8140: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8150: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
8160: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8170: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
8180: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8190: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
81a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81b0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
81c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81d0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
81e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81f0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
8200: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8210: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8220: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8230: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8240: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8250: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
8260: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8270: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
8280: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8290: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
82a0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
82b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
82c0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
82d0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
82e0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
82f0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
8300: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8310: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8320: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8330: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8340: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8350: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8360: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8370: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
8380: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
8390: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
83a0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
83b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
83c0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
83d0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
83e0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
83f0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8400: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8410: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8420: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8430: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8440: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8450: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8460: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8470: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
8480: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
8490: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
84a0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
84b0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
84c0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
84d0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
84e0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
84f0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8500: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8510: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8520: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8530: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8540: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8550: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8560: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8570: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8580: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
8590: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
85a0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
85b0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
85c0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
85d0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
85e0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
85f0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8600: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8610: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8620: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8630: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8640: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8650: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8660: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8680: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
8690: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
86a0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
86b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
86c0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
86d0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
86e0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
86f0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8700: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8710: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8720: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8730: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8740: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8750: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8760: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8770: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
8780: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8790: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
87a0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
87b0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
87c0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
87d0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
87e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
87f0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8800: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8810: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8820: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8830: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8840: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8850: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8860: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8870: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
8880: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8890: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
88a0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
88b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
88c0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
88d0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
88e0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
88f0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8900: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8910: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8920: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8930: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8940: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8950: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8960: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8970: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
8980: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
8990: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
89a0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
89b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
89c0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
89d0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
89e0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
89f0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
8a00: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
8a10: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8a20: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8a30: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8a40: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
8a50: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8a60: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8a70: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
8a80: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
8a90: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8aa0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8ab0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
8ac0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
8ad0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
8ae0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
8af0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
8b00: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
8b10: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8b20: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
8b30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8b40: 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74  odes} {file cont
8b50: 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a  rol opcode}.**.*
8b60: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8b70: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
8b80: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
8b90: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8ba0: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
8bb0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8bc0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
8bd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8be0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
8bf0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
8c00: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53   <ul>.** <li>[[S
8c10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
8c20: 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  STATE]].** The [
8c30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
8c40: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
8c50: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
8c60: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
8c70: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
8c80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8c90: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
8ca0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
8cb0: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
8cc0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
8cd0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
8ce0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
8cf0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
8d00: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
8d10: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8d20: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
8d30: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
8d40: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
8d50: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
8d60: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
8d70: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
8d80: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
8d90: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
8da0: 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  d is only availa
8db0: 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c  ble when the SQL
8dc0: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70  ITE_TEST.** comp
8dd0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
8de0: 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
8df0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8e00: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a  L_SIZE_HINT]].**
8e10: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8e20: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70  TL_SIZE_HINT] op
8e30: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
8e40: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74  SQLite to give t
8e50: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20  he VFS.** layer 
8e60: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61  a hint of how la
8e70: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  rge the database
8e80: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20   file will grow 
8e90: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65  to be during the
8ea0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e  .** current tran
8eb0: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68  saction.  This h
8ec0: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61  int is not guara
8ed0: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75  nteed to be accu
8ee0: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69  rate but it.** i
8ef0: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20  s often close.  
8f00: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56  The underlying V
8f10: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20  FS might choose 
8f20: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64  to preallocate d
8f30: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8f40: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74  space based on t
8f50: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65  his hint in orde
8f60: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73  r to help writes
8f70: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
8f80: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73  .** file run fas
8f90: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
8fa0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8fb0: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
8fc0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8fd0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
8fe0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
8ff0: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
9000: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
9010: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
9020: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
9030: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
9040: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
9050: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
9060: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
9070: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
9080: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
9090: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
90a0: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
90b0: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
90c0: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
90d0: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
90e0: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
90f0: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
9100: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
9110: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
9120: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
9130: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
9140: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
9150: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
9160: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
9170: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
9180: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
9190: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
91a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
91b0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
91c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
91d0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
91e0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
91f0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
9200: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
9210: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9220: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9230: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9240: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9250: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
9260: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
9270: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  RNAL_POINTER]..*
9280: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9290: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
92a0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
92b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
92c0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20  OURNAL_POINTER] 
92d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
92e0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
92f0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9300: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9310: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9320: 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66  th the journal f
9330: 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74  ile (either.** t
9340: 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75  he [rollback jou
9350: 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72  rnal] or the [wr
9360: 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20  ite-ahead log]) 
9370: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
9380: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9390: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c  nection.  See al
93a0: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  so [SQLITE_FCNTL
93b0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a  _FILE_POINTER]..
93c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
93d0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
93e0: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
93f0: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9400: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9410: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
9420: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9430: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
9440: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9450: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9460: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
9470: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
9480: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
9490: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
94a0: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
94b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
94c0: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
94d0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
94e0: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
94f0: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9500: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9510: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
9520: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
9530: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
9540: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
9550: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
9560: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
9570: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9580: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
9590: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
95a0: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
95b0: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
95c0: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
95d0: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
95e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
95f0: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9600: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
9610: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
9620: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
9630: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
9640: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
9650: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
9660: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
9670: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
9680: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
9690: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
96a0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
96b0: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
96c0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
96d0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
96e0: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
96f0: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9700: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9710: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9720: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9730: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
9740: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
9750: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9760: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9770: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9780: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9790: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
97a0: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
97b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
97c0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
97d0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
97e0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
97f0: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
9800: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
9810: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
9820: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
9830: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
9840: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
9850: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
9860: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
9870: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
9880: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
9890: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
98a0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
98b0: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
98c0: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
98d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
98e0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
98f0: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9900: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9910: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
9920: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9930: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9940: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9950: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9960: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9970: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
9980: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9990: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
99a0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
99b0: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
99c0: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
99d0: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
99e0: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
99f0: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9a00: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9a10: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
9a20: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
9a30: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
9a40: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
9a50: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
9a60: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
9a70: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
9a80: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
9a90: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
9aa0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9ab0: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9ac0: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9ad0: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9ae0: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9af0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9b00: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9b10: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
9b20: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
9b30: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
9b40: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
9b50: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
9b60: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
9b70: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9b80: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
9b90: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
9ba0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9bb0: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9bc0: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9bd0: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9be0: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9bf0: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9c00: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9c10: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
9c20: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
9c30: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
9c40: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
9c50: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
9c60: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
9c70: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
9c80: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
9c90: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
9ca0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9cb0: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9cc0: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9cd0: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9ce0: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9cf0: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9d00: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9d10: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
9d20: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
9d30: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
9d40: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
9d50: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
9d60: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
9d70: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9d80: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9d90: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9da0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9db0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9dc0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9dd0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9de0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9df0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9e00: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9e10: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
9e20: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
9e30: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
9e40: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
9e50: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
9e60: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
9e70: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
9e80: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
9e90: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
9ea0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
9eb0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
9ec0: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
9ed0: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
9ee0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9ef0: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
9f00: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
9f10: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
9f20: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
9f30: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
9f40: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
9f50: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
9f60: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
9f70: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
9f80: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
9f90: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
9fa0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
9fb0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
9fc0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
9fd0: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
9fe0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
9ff0: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
a000: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a010: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
a020: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
a030: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
a040: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
a050: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a060: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a070: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a080: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a090: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a0a0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a0b0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a0c0: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a0d0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
a0e0: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
a0f0: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
a100: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
a110: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a120: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a130: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a140: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a150: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
a160: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a170: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a180: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a190: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a1a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a1b0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a1c0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
a1d0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
a1e0: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
a1f0: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
a200: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
a210: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
a220: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
a230: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
a240: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
a250: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a260: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
a270: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
a280: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
a290: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
a2a0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a2b0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a2c0: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a2d0: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a2e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a2f0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a300: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a310: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
a320: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
a330: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
a340: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
a350: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a360: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a370: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a380: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a390: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a3a0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a3b0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a3c0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
a3d0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a3e0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
a3f0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
a400: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
a410: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
a420: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
a430: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
a440: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
a450: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
a460: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
a470: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
a480: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
a490: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
a4a0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
a4b0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
a4c0: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
a4d0: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
a4e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a4f0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a500: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a510: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a520: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
a530: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
a540: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
a550: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
a560: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
a570: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
a580: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
a590: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
a5a0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
a5b0: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
a5c0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
a5d0: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
a5e0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
a5f0: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
a600: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
a610: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
a620: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
a630: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
a640: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a650: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
a660: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
a670: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
a680: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
a690: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
a6a0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
a6b0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
a6c0: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
a6d0: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
a6e0: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
a6f0: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
a700: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
a710: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
a720: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
a730: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
a740: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
a750: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
a760: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
a770: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a780: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a790: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a7a0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a7b0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a7c0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
a7d0: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
a7e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
a7f0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66  OINTER] opcode f
a800: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74  inds a pointer t
a810: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a  o the top-level.
a820: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65  ** [VFSes] curre
a830: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28  ntly in use.  ^(
a840: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69  The argument X i
a850: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c  n.** sqlite3_fil
a860: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c  e_control(db,SQL
a870: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
a880: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65  INTER,X) must be
a890: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71  .** of type "[sq
a8a0: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20  lite3_vfs] **". 
a8b0: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69   This opcodes wi
a8c0: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20  ll set *X.** to 
a8d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
a8e0: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29   top-level VFS.)
a8f0: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65  ^.** ^When there
a900: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46   are multiple VF
a910: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73  S shims in the s
a920: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64  tack, this opcod
a930: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75  e finds the.** u
a940: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f  pper-most shim o
a950: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a960: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a970: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a980: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a990: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a9a0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a9b0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a9c0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a9d0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a9e0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a9f0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
aa00: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
aa10: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
aa20: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
aa30: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
aa40: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
aa50: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
aa60: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aa70: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
aa80: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
aa90: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
aaa0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
aab0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
aac0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
aad0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
aae0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
aaf0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
ab00: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
ab10: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
ab20: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
ab30: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
ab40: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
ab50: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
ab60: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
ab70: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ab80: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
ab90: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
aba0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
abb0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
abc0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
abd0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
abe0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
abf0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
ac00: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
ac10: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
ac20: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
ac30: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
ac40: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
ac50: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
ac60: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
ac70: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
ac80: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
ac90: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
aca0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
acb0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
acc0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
acd0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
ace0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
acf0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
ad00: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
ad10: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
ad20: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
ad30: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
ad40: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
ad50: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
ad60: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
ad70: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
ad80: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
ad90: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
ada0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
adb0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
adc0: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
add0: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
ade0: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
adf0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
ae00: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
ae10: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
ae20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ae30: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ae40: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
ae50: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
ae60: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
ae70: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
ae80: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
ae90: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
aea0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
aeb0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
aec0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
aed0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
aee0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
aef0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
af00: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
af10: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
af20: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
af30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
af40: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
af50: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
af60: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
af70: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
af80: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
af90: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
afa0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
afb0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
afc0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
afd0: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
afe0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
aff0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
b000: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
b010: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
b020: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
b030: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
b040: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
b050: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
b060: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
b070: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
b080: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
b090: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
b0a0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
b0b0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
b0c0: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
b0d0: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
b0e0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
b0f0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
b100: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
b110: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
b120: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
b130: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
b140: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
b150: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
b160: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
b170: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
b180: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
b190: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
b1a0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
b1b0: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
b1c0: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
b1d0: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
b1e0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
b1f0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
b200: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
b210: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
b220: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
b230: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
b240: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
b250: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
b260: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
b270: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b280: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b290: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
b2a0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
b2b0: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
b2c0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b2d0: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
b2e0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
b2f0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
b300: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b310: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b320: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b330: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b340: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b350: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b360: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b370: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b380: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b390: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b3a0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b3b0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b3c0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b3d0: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b3e0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b3f0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b400: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b410: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b420: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b430: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b440: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b450: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b460: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b470: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b480: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b490: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b4a0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b4b0: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b4c0: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b4d0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b4e0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b4f0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b500: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b510: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b520: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b530: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b540: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b550: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b560: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b570: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b580: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b590: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b5a0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b5b0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b5c0: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b5d0: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b5e0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b5f0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b600: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b610: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b620: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b630: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b640: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b650: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b660: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b670: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b680: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b690: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b6a0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b6b0: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b6c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b6d0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b6e0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b6f0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b700: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b710: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b720: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b730: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b740: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b750: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b760: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b770: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b780: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b790: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b7a0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b7b0: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b7c0: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b7d0: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b7e0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b7f0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
b800: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
b810: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
b820: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
b830: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
b840: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
b850: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
b860: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
b870: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
b880: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b890: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
b8a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
b8b0: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
b8c0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
b8d0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
b8e0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
b8f0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
b900: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
b910: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
b920: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
b930: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
b940: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
b950: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
b960: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
b970: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
b980: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
b990: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b9a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b9b0: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
b9c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b9d0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b9e0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
b9f0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
ba00: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
ba10: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
ba20: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
ba30: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
ba40: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
ba50: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
ba60: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
ba70: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
ba80: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
ba90: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
baa0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
bab0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
bac0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
bad0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
bae0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
baf0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
bb00: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
bb10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
bb20: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
bb30: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
bb40: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
bb50: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
bb60: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
bb70: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
bb80: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
bb90: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
bba0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
bbb0: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
bbc0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
bbd0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
bbe0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
bbf0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
bc00: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
bc10: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
bc20: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
bc30: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
bc40: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
bc50: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
bc60: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bc70: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
bc80: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bc90: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
bca0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
bcb0: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
bcc0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
bcd0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
bce0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
bcf0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
bd00: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
bd10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
bd20: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
bd30: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
bd40: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
bd50: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
bd60: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
bd70: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
bd80: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
bd90: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
bda0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
bdb0: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
bdc0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20  is opcode.  .** 
bdd0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
bde0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
bdf0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
be00: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
be10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
be20: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
be30: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
be40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
be50: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
be60: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
be70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
be80: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
be90: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
bea0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
beb0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
bec0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
bed0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
bee0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
bef0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
bf00: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
bf10: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
bf20: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
bf30: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
bf40: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
bf50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf60: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
bf70: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
bf80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bf90: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
bfa0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
bfb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bfc0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
bfd0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
bfe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bff0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
c000: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
c010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c020: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
c030: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
c040: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c050: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
c060: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
c070: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c080: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
c090: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
c0a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
c0b0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
c0c0: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
c0d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
c0e0: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
c0f0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
c100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
c110: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
c120: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
c130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
c140: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
c150: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
c160: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
c170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c180: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
c190: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c1a0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
c1b0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
c1c0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c1d0: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
c1e0: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
c1f0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
c200: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
c210: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c220: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
c230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
c240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c250: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
c260: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
c270: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c280: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
c290: 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23              27.#
c2a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c2b0: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
c2c0: 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 0a 2f  TER        28../
c2d0: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d  * deprecated nam
c2e0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
c2f0: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
c300: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c310: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
c320: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c330: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
c340: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c350: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
c360: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
c370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
c380: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
c390: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c3a0: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a  TL_LAST_ERRNO...
c3b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c3c0: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
c3d0: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
c3e0: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
c3f0: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
c400: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
c410: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
c420: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
c430: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
c440: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
c450: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
c460: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
c470: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
c480: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
c490: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
c4a0: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
c4b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
c4c0: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
c4d0: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
c4e0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
c4f0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
c500: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
c510: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c520: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
c530: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
c540: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
c550: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
c560: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c570: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
c580: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
c590: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
c5a0: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
c5b0: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
c5c0: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
c5d0: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
c5e0: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
c5f0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
c600: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
c610: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
c620: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
c630: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
c640: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
c650: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
c660: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
c670: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
c680: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
c690: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
c6a0: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
c6b0: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
c6c0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
c6d0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
c6e0: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
c6f0: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
c700: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
c710: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
c720: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
c730: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
c740: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
c750: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
c760: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
c770: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
c780: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
c790: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
c7a0: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
c7b0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
c7c0: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
c7d0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
c7e0: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
c7f0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
c800: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
c810: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
c820: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
c830: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
c840: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
c850: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
c860: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
c870: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
c880: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
c890: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
c8a0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
c8b0: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
c8c0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
c8d0: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
c8e0: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
c8f0: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
c900: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
c910: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
c920: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
c930: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
c940: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
c950: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
c960: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
c970: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
c980: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
c990: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
c9a0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
c9b0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
c9c0: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
c9d0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
c9e0: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
c9f0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
ca00: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
ca10: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
ca20: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
ca30: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
ca40: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
ca50: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
ca60: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
ca70: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
ca80: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
ca90: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
caa0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
cab0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
cac0: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
cad0: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
cae0: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
caf0: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
cb00: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
cb10: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
cb20: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
cb30: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
cb40: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
cb50: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
cb60: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
cb70: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
cb80: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
cb90: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
cba0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
cbb0: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
cbc0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
cbd0: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
cbe0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
cbf0: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
cc00: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
cc10: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
cc20: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
cc30: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
cc40: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
cc50: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
cc60: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
cc70: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
cc80: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
cc90: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
cca0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
ccb0: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
ccc0: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
ccd0: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
cce0: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
ccf0: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
cd00: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
cd10: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
cd20: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
cd30: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
cd40: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
cd50: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
cd60: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
cd70: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
cd80: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
cd90: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
cda0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
cdb0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
cdc0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
cdd0: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
cde0: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
cdf0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
ce00: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
ce10: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
ce20: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
ce30: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
ce40: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
ce50: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
ce60: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
ce70: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
ce80: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
ce90: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
cea0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
ceb0: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
cec0: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
ced0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
cee0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
cef0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
cf00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
cf10: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
cf20: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
cf30: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
cf40: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
cf50: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
cf60: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
cf70: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
cf80: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
cf90: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
cfa0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
cfb0: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
cfc0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
cfd0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
cfe0: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
cff0: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
d000: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
d010: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
d020: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
d030: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
d040: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
d050: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
d060: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
d070: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
d080: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
d090: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
d0a0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
d0b0: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
d0c0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
d0d0: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
d0e0: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
d0f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d100: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
d110: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
d130: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d140: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
d150: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d160: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
d170: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d180: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
d190: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
d1a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d1b0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
d1c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d1d0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
d1e0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
d1f0: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
d200: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
d210: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
d220: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
d230: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
d240: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
d250: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
d260: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
d270: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
d280: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
d290: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
d2a0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
d2b0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
d2c0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
d2d0: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
d2e0: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
d2f0: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
d300: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
d310: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
d320: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
d330: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
d340: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
d350: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
d360: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
d370: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
d380: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
d390: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
d3a0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
d3b0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
d3c0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
d3d0: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
d3e0: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
d3f0: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
d400: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
d410: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
d420: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
d430: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
d440: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
d450: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
d460: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d470: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
d480: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d490: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
d4a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
d4b0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
d4c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
d4d0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d4e0: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
d4f0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
d500: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
d510: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
d520: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
d530: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d540: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
d550: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
d560: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
d570: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
d580: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
d590: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
d5a0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
d5b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d5c0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
d5d0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
d5e0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
d5f0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
d600: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
d610: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
d620: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
d630: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
d640: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
d650: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
d660: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
d670: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
d680: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
d690: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
d6a0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
d6b0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
d6c0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
d6d0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
d6e0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
d6f0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
d700: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
d710: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
d720: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
d730: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
d740: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
d750: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
d760: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
d770: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
d780: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
d790: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
d7a0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
d7b0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
d7c0: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
d7d0: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
d7e0: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
d7f0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
d800: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
d810: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
d820: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
d830: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
d840: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
d850: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
d860: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
d870: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
d880: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
d890: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
d8a0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
d8b0: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
d8c0: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
d8d0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
d8e0: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
d8f0: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
d900: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
d910: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
d920: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
d930: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
d940: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
d950: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
d960: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
d970: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
d980: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
d990: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
d9a0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
d9b0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
d9c0: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
d9d0: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
d9e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
d9f0: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
da00: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
da10: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
da20: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
da30: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
da40: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
da50: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
da60: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
da70: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
da80: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
da90: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
daa0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
dab0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
dac0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
dad0: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
dae0: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
daf0: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
db00: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
db10: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
db20: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
db30: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
db40: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
db50: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
db60: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
db70: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
db80: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
db90: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
dba0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
dbb0: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
dbc0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
dbd0: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
dbe0: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
dbf0: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
dc00: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
dc10: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
dc20: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
dc30: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
dc40: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
dc50: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
dc60: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
dc70: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
dc80: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
dc90: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
dca0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
dcb0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
dcc0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
dcd0: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
dce0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
dcf0: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
dd00: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
dd10: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
dd20: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
dd30: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
dd40: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
dd50: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
dd60: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
dd70: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
dd80: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
dd90: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
dda0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
ddb0: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
ddc0: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
ddd0: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
dde0: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
ddf0: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
de00: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
de10: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
de20: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
de30: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
de40: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
de50: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
de60: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
de70: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
de80: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
de90: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
dea0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
deb0: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
dec0: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
ded0: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
dee0: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
def0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
df00: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
df10: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
df20: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
df30: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
df40: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
df50: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
df60: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
df70: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
df80: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
df90: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
dfa0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
dfb0: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
dfc0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
dfd0: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
dfe0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
dff0: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
e000: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
e010: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
e020: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
e030: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
e040: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
e050: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
e060: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
e070: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
e080: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
e090: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
e0a0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
e0b0: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
e0c0: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
e0d0: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
e0e0: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
e0f0: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
e100: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
e110: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
e120: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
e130: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
e140: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
e150: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
e160: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
e170: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
e180: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
e190: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
e1a0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
e1b0: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
e1c0: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
e1d0: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
e1e0: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
e1f0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
e200: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
e210: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
e220: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
e230: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
e240: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
e250: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
e260: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
e270: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
e280: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
e290: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
e2a0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
e2b0: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
e2c0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
e2d0: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
e2e0: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
e2f0: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
e300: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
e310: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e320: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
e330: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
e340: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
e350: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
e360: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
e370: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
e380: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
e390: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
e3a0: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
e3b0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
e3c0: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
e3d0: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
e3e0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
e3f0: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
e400: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
e410: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
e420: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
e430: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
e440: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
e450: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
e460: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
e470: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
e480: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
e490: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
e4a0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
e4b0: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
e4c0: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
e4d0: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
e4e0: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
e4f0: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
e500: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
e510: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
e520: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
e530: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
e540: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
e550: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
e560: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
e570: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
e580: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
e590: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
e5a0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
e5b0: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
e5c0: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
e5d0: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
e5e0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e5f0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
e600: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
e610: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
e620: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
e630: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
e640: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e650: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e660: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
e670: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
e680: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
e690: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e6a0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
e6b0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
e6c0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
e6d0: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
e6e0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e6f0: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
e700: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
e710: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
e720: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e730: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
e740: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
e750: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
e760: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
e770: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
e780: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
e790: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
e7a0: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
e7b0: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
e7c0: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
e7d0: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
e7e0: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
e7f0: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
e800: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
e810: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
e820: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
e830: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
e840: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
e850: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
e860: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
e870: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
e880: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
e890: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
e8a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e8b0: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
e8c0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e8d0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e8e0: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
e8f0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e900: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
e910: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
e920: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
e930: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
e940: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
e950: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
e960: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
e970: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
e980: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
e990: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e9a0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e9b0: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
e9c0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e9d0: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
e9e0: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
e9f0: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
ea00: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
ea10: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
ea20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ea30: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ea40: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
ea50: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
ea60: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
ea70: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
ea80: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ea90: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
eaa0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
eab0: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
eac0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ead0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
eae0: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
eaf0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
eb00: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
eb10: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
eb20: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
eb30: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
eb40: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
eb50: 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  ended in future 
eb60: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
eb70: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
eb80: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
eb90: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
eba0: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
ebb0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ebc0: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
ebd0: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
ebe0: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
ebf0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
ec00: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
ec10: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
ec20: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
ec30: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
ec40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
ec50: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
ec60: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
ec70: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
ec80: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
ec90: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
eca0: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
ecb0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
ecc0: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
ecd0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
ece0: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
ecf0: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
ed00: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
ed10: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
ed20: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
ed30: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
ed40: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
ed50: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
ed60: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
ed70: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
ed80: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
ed90: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
eda0: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
edb0: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
edc0: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
edd0: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
ede0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
edf0: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
ee00: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
ee10: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
ee20: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
ee30: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
ee40: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
ee50: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
ee60: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
ee70: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
ee80: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
ee90: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
eea0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
eeb0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
eec0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
eed0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
eee0: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
eef0: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
ef00: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
ef10: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
ef20: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
ef30: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
ef40: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
ef50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
ef60: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
ef70: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ef80: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
ef90: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
efa0: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
efb0: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
efc0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
efd0: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
efe0: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
eff0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
f000: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
f010: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
f020: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
f030: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
f040: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
f050: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
f060: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
f070: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
f080: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
f090: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
f0a0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
f0b0: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
f0c0: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
f0d0: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
f0e0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
f0f0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
f100: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
f110: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f120: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
f130: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f140: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
f150: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
f160: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
f170: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
f180: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
f190: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
f1a0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
f1b0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
f1c0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
f1d0: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
f1e0: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
f1f0: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
f200: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
f210: 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65  was given on the
f220: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
f230: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
f240: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f250: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
f260: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
f270: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
f280: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
f290: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
f2a0: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
f2b0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f2c0: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
f2d0: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
f2e0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
f2f0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
f300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f310: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
f320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f330: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
f340: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
f350: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
f360: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
f370: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
f380: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
f390: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
f3a0: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
f3b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
f3c0: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
f3d0: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
f3e0: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
f3f0: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
f400: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
f410: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
f420: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
f430: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
f440: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
f450: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
f460: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
f470: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
f480: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
f490: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
f4a0: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
f4b0: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
f4c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f4d0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f4e0: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
f4f0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
f500: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
f510: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
f520: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
f530: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
f540: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
f550: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
f560: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
f570: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
f580: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
f590: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
f5a0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f5b0: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
f5c0: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
f5d0: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
f5e0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
f5f0: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
f600: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
f610: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
f620: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
f630: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
f640: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f650: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f660: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
f670: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
f680: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
f690: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f6a0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
f6b0: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
f6c0: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
f6d0: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
f6e0: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
f6f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f700: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f710: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
f720: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f730: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
f740: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
f750: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
f760: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f770: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
f780: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
f790: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
f7a0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
f7b0: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
f7c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f7d0: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
f7e0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
f7f0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
f800: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
f810: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f820: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
f830: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f840: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
f850: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
f860: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f870: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
f880: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
f890: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
f8a0: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
f8b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f8c0: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
f8d0: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
f8e0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
f8f0: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
f900: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
f910: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
f920: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
f930: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
f940: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
f950: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
f960: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
f970: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
f980: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
f990: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f9a0: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
f9b0: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
f9c0: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
f9d0: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
f9e0: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
f9f0: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
fa00: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
fa10: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
fa20: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
fa30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fa40: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
fa50: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fa60: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
fa70: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fa80: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
fa90: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
faa0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
fab0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fac0: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
fad0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
fae0: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
faf0: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
fb00: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
fb10: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
fb20: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
fb30: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
fb40: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
fb50: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
fb60: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
fb70: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
fb80: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
fb90: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
fba0: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
fbb0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
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 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
fbf0: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
fc00: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
fc10: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
fc20: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
fc30: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
fc40: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
fc50: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
fc60: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
fc70: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
fc80: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
fc90: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
fca0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fcb0: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
fcc0: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
fcd0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
fce0: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
fcf0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
fd00: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
fd10: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
fd20: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
fd30: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
fd40: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
fd50: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
fd60: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
fd70: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
fd80: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
fd90: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
fda0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
fdb0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
fdc0: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
fdd0: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
fde0: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
fdf0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fe00: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
fe10: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
fe20: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
fe30: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
fe40: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
fe50: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
fe60: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
fe70: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
fe80: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
fe90: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
fea0: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
feb0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
fec0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fed0: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
fee0: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
fef0: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
ff00: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
ff10: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
ff20: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
ff30: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
ff40: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
ff50: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
ff60: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
ff70: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
ff80: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
ff90: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
ffa0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
ffb0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
ffc0: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
ffd0: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
ffe0: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
fff0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
10000 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10010 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
10020 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
10030 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
10040 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
10050 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
10060 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
10070 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
10080 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
10090 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
100a0 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
100b0 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
100c0 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
100d0 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
100e0 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
100f0 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
10100 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
10110 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
10120 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
10130 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
10140 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
10150 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
10160 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
10170 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
10180 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
10190 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
101a0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
101b0 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
101c0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
101d0 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
101e0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
101f0 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
10200 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10210 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
10220 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
10230 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
10240 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
10250 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
10260 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
10270 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
10280 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
10290 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
102a0 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
102b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
102c0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
102d0 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
102e0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
102f0 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
10300 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
10310 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
10320 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
10330 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
10340 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
10350 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
10360 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
10370 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
10380 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
10390 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
103a0 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
103b0 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
103c0 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
103d0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
103e0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
103f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
10400 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
10410 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
10420 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
10430 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
10440 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
10450 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
10460 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
10470 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
10480 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
10490 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
104a0 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
104b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
104c0 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
104d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
104e0 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
104f0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10500 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
10510 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
10520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10530 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
10540 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
10550 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10560 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
10570 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
10580 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
10590 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
105a0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
105b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
105c0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
105d0 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
105e0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
105f0 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
10600 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
10610 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
10620 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
10630 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
10640 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
10650 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
10660 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
10670 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
10680 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
10690 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
106a0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
106b0 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  <b>The sqlite3_c
106c0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
106d0 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
106e0 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61  afe. The applica
106f0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
10700 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
10710 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10720 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
10730 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
10740 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
10750 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
10760 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  nning.</b>.**.**
10770 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
10780 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a  fig() interface.
10790 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
107a0 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
107b0 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
107c0 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
107d0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
107e0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
107f0 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
10800 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10810 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
10820 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
10830 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
10840 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
10850 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
10860 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10870 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
10880 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
10890 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
108a0 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
108b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
108c0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
108d0 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
108e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
108f0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
10900 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
10910 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
10920 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
10930 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
10940 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
10950 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
10960 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10970 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
10980 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
10990 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
109a0 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
109b0 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
109c0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
109d0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
109e0 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
109f0 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
10a00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10a10 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
10a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10a30 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
10a40 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
10a50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
10a60 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
10a70 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
10a80 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
10a90 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
10aa0 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
10ab0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
10ac0 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
10ad0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
10ae0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
10af0 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
10b00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10b10 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
10b20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
10b30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
10b40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10b50 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
10b60 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
10b70 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
10b80 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
10b90 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
10ba0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
10bb0 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
10bc0 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
10bd0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10be0 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
10bf0 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
10c00 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
10c10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10c20 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
10c30 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10c40 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
10c50 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10c60 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
10c70 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
10c80 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
10c90 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10ca0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
10cb0 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
10cc0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
10cd0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
10ce0 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
10cf0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10d00 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
10d10 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
10d20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10d30 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
10d40 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
10d50 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
10d60 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
10d70 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10d80 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
10d90 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
10da0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
10db0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
10dc0 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
10dd0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10de0 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
10df0 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
10e00 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
10e10 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
10e20 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
10e30 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10e40 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
10e50 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
10e60 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
10e70 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
10e80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10e90 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
10ea0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
10eb0 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
10ec0 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
10ed0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
10ee0 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
10ef0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10f00 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
10f10 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10f20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10f30 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
10f40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10f50 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
10f60 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
10f70 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10f80 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
10f90 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
10fa0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10fb0 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
10fc0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
10fd0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
10fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10ff0 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
11000 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
11010 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
11020 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
11030 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
11040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
11050 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
11060 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
11070 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
11080 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
11090 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
110a0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
110b0 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
110c0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
110d0 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
110e0 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
110f0 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
11100 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
11110 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
11120 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
11130 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
11140 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
11150 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
11160 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
11170 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
11180 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
11190 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
111a0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
111b0 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
111c0 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
111d0 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
111e0 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
111f0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
11200 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11210 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
11220 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
11230 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
11240 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
11250 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
11260 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
11270 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
11280 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
11290 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
112a0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
112b0 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
112c0 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
112d0 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
112e0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
112f0 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
11300 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
11310 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
11320 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
11330 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
11340 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
11350 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
11360 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
11370 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
11380 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
11390 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
113a0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
113b0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
113c0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
113d0 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
113e0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
113f0 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
11400 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
11410 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
11420 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
11430 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
11440 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
11450 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
11460 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
11470 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
11480 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
11490 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
114a0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
114b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
114c0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
114d0 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
114e0 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
114f0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
11500 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
11510 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
11520 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
11530 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
11540 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
11550 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
11560 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
11570 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
11580 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
11590 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
115a0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
115b0 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
115c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
115d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
115e0 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
115f0 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
11600 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
11610 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
11620 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
11630 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
11640 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
11650 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
11660 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
11670 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
11680 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
11690 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
116a0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
116b0 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
116c0 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
116d0 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
116e0 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
116f0 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
11700 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
11710 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
11720 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11730 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
11740 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
11750 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
11760 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
11770 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
11780 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
11790 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
117a0 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
117b0 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
117c0 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
117d0 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
117e0 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
117f0 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
11800 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
11810 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
11820 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
11830 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
11840 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
11850 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
11860 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
11870 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
11880 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
11890 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
118a0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
118b0 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
118c0 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
118d0 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
118e0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
118f0 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
11900 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
11910 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
11920 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
11930 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11940 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
11950 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
11960 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
11970 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
11980 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
11990 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
119a0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
119b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
119c0 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
119d0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
119e0 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
119f0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11a00 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
11a10 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
11a20 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
11a30 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
11a40 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
11a50 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
11a60 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
11a70 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
11a80 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
11a90 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
11aa0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11ab0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11ac0 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
11ad0 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
11ae0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11af0 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
11b00 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
11b10 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
11b20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
11b30 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
11b40 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
11b50 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
11b60 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
11b70 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
11b80 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
11b90 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
11ba0 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
11bb0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
11bc0 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
11bd0 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
11be0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
11bf0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11c00 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
11c10 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
11c20 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
11c30 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
11c40 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
11c50 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
11c60 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
11c70 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
11c80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11c90 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
11ca0 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
11cb0 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
11cc0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11cd0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11ce0 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
11cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11d00 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
11d10 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
11d20 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
11d30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11d40 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
11d50 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
11d60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11d70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
11d80 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
11d90 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
11da0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
11db0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
11dc0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
11dd0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
11de0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
11df0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11e00 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
11e10 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
11e20 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
11e30 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
11e40 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
11e50 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
11e60 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
11e70 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
11e80 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
11e90 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
11ea0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
11eb0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
11ec0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
11ed0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
11ee0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
11ef0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
11f00 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11f10 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
11f20 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
11f30 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
11f40 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
11f50 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
11f60 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
11f70 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
11f80 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
11f90 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
11fa0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11fb0 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11fc0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11fd0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11fe0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11ff0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12000 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12010 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12020 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12030 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
12040 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
12050 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
12060 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
12070 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
12080 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
12090 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
120a0 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
120b0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
120c0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
120d0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
120e0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
120f0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12100 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12110 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12120 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
12130 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
12140 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
12150 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
12160 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
12170 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
12180 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
12190 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
121a0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
121b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
121c0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
121d0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
121e0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
121f0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12200 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12210 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12220 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
12230 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12240 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
12250 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
12260 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
12270 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
12280 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
12290 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
122a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
122b0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
122c0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
122d0 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
122e0 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
122f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12300 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12310 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
12320 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
12330 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
12340 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
12350 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
12360 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12370 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
12380 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12390 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
123a0 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
123b0 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
123c0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
123d0 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
123e0 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
123f0 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
12400 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
12410 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
12420 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
12430 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12440 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
12450 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
12460 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12470 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12480 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12490 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
124a0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
124b0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
124c0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
124d0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
124e0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
124f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
12500 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
12510 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12520 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12530 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12540 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
12550 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
12560 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
12570 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12580 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12590 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
125a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
125b0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
125c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
125d0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
125e0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
125f0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12600 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12610 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12620 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
12630 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
12640 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
12650 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
12660 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
12670 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
12680 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
12690 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
126a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
126b0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
126c0 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
126d0 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
126e0 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
126f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12700 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
12710 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
12720 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
12730 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
12740 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
12750 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12760 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
12770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
12780 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
12790 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
127a0 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
127b0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
127c0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
127d0 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
127e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
127f0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
12800 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
12810 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
12820 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12830 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12840 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
12850 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12860 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12870 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12880 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
12890 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
128a0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
128b0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
128c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
128d0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
128e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
128f0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
12900 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
12910 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
12920 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12930 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12940 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12950 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
12960 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12970 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
12980 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
12990 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  IG_MALLOC option
129a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
129b0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
129c0 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
129d0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
129e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
129f0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12a00 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
12a10 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
12a20 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
12a30 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12a40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12a50 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
12a60 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
12a70 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12a80 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
12a90 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
12aa0 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
12ab0 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
12ac0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
12ad0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
12ae0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12af0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
12b00 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
12b10 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12b20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
12b30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12b40 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12b50 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
12b60 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12b70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12b80 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12b90 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69  G_GETMALLOC opti
12ba0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12bb0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12bc0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
12bd0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
12be0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12bf0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12c00 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b  ucture..** The [
12c10 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12c20 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
12c30 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
12c40 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
12c50 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
12c60 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12c70 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
12c80 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12c90 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12ca0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12cb0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
12cc0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
12cd0 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
12ce0 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
12cf0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
12d00 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
12d10 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
12d20 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
12d30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12d40 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
12d50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12d60 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
12d70 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
12d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12d90 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b  TATUS option tak
12da0 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
12db0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a  nt of type int,.
12dc0 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ** interpreted a
12dd0 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
12de0 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
12df0 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
12e00 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f  ction of.** memo
12e10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12e20 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
12e30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12e40 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
12e50 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74  e.** disabled, t
12e60 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
12e70 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
12e80 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
12e90 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
12ea0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12eb0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
12ec0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
12ed0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
12ee0 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
12ef0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
12f00 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
12f10 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12f20 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d  ite3_status64()]
12f30 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
12f40 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
12f50 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
12f60 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
12f70 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
12f80 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
12f90 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
12fa0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
12fb0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
12fc0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
12fd0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12fe0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
12ff0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
13000 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13010 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13020 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
13030 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
13040 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13050 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13060 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70  CRATCH option sp
13070 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
13080 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
13090 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
130a0 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63  n use for scratc
130b0 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65  h memory.  ^(The
130c0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
130d0 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c  uments.** to SQL
130e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
130f0 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  CH:  A pointer a
13100 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
13110 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
13120 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
13130 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13140 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
13150 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
13160 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
13170 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
13180 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
13190 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
131a0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
131b0 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20  s (N).)^.** The 
131c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
131d0 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
131e0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
131f0 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
13200 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
13210 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
13220 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
13230 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74  l not use more t
13240 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
13250 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
13260 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ad..** ^SQLite w
13270 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73  ill never reques
13280 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  t a scratch buff
13290 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
132a0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
132b0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
132c0 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53  e size..** ^If S
132d0 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
132e0 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
132f0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
13300 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
13310 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
13320 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13330 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
13340 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13350 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
13360 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
13370 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a  ry needed.<p>.**
13380 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69   ^When the appli
13390 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20  cation provides 
133a0 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63  any amount of sc
133b0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69  ratch memory usi
133c0 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  ng.** SQLITE_CON
133d0 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c  FIG_SCRATCH, SQL
133e0 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63  ite avoids unnec
133f0 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20  essary large.** 
13400 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c  [sqlite3_malloc|
13410 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  heap allocations
13420 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68  ]..** This can h
13430 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f  elp [Robson proo
13440 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79  f|prevent memory
13450 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
13460 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61  ures] due to hea
13470 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69  p.** fragmentati
13480 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79  on in low-memory
13490 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
134a0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
134b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
134c0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
134d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
134e0 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
134f0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
13500 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13510 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  CHE option speci
13520 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f  fies a memory po
13530 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  ol.** that SQLit
13540 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68  e can use for th
13550 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
13560 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
13570 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63  efault page.** c
13580 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13590 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
135a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
135b0 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69  ion is a no-op i
135c0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
135d0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
135e0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
135f0 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
13600 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
13610 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
13620 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
13630 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
13640 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
13650 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f  _PAGECACHE: A po
13660 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79  inter to.** 8-by
13670 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  te aligned memor
13680 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69  y (pMem), the si
13690 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
136a0 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c  cache line (sz),
136b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  .** and the numb
136c0 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65  er of cache line
136d0 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
136e0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
136f0 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
13700 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
13710 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
13720 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
13730 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35  ween 512 and 655
13740 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78  36) plus some ex
13750 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61  tra bytes for ea
13760 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
13770 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  r.  ^The number 
13780 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e  of extra bytes n
13790 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67  eeded by the pag
137a0 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20  e header.** can 
137b0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
137c0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ing [SQLITE_CONF
137d0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
137e0 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d  ..** ^It is harm
137f0 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
13800 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
13810 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ry,.** for the s
13820 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  z parameter to b
13830 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65  e larger than ne
13840 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d  cessary.  The pM
13850 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  em.** argument m
13860 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
13870 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
13880 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13890 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65  8-byte.** aligne
138a0 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  d block of memor
138b0 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  y of at least sz
138c0 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77  *N bytes, otherw
138d0 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e  ise.** subsequen
138e0 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  t behavior is un
138f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65  defined..** ^Whe
13900 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55  n pMem is not NU
13910 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
13920 73 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68  strive to use th
13930 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
13940 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20  d.** to satisfy 
13950 70 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73  page cache needs
13960 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74  , falling back t
13970 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
13980 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67  c()] if.** a pag
13990 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20  e cache line is 
139a0 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62  larger than sz b
139b0 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f  ytes or if all o
139c0 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65  f the pMem buffe
139d0 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65  r.** is exhauste
139e0 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69  d..** ^If pMem i
139f0 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
13a00 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65  non-zero, then e
13a10 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
13a20 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20  nection.** does 
13a30 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20  an initial bulk 
13a40 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70  allocation for p
13a50 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13a60 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
13a70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66  3_malloc()] suff
13a80 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63  icient for N cac
13a90 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73  he lines if N is
13aa0 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20   positive or.** 
13ab0 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73  of -1024*N bytes
13ac0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
13ad0 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f  e, . ^If additio
13ae0 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
13af0 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
13b00 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
13b10 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
13b20 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c  e initial.** all
13b30 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51  ocation, then SQ
13b40 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
13b50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13b60 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65  separately for e
13b70 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  ach.** additiona
13b80 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f  l cache line. </
13b90 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13ba0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
13bb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13bc0 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
13bd0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
13be0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
13bf0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
13c00 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
13c10 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51  ffer .** that SQ
13c20 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f  Lite will use fo
13c30 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
13c40 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
13c50 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20  cation needs.** 
13c60 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
13c70 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51  vided for by [SQ
13c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13c90 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c  TCH] and.** [SQL
13ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13cb0 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53  ACHE]..** ^The S
13cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13cd0 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  P option is only
13ce0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
13cf0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13d00 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20  .** with either 
13d10 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
13d20 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49  EMSYS3] or [SQLI
13d30 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
13d40 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  5] and returns.*
13d50 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
13d60 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65   if invoked othe
13d70 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65  rwise..** ^There
13d80 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
13d90 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
13da0 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41  ONFIG_HEAP:.** A
13db0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
13dc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
13dd0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
13de0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
13df0 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
13e00 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
13e10 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
13e20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
13e30 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
13e40 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
13e50 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
13e60 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
13e70 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
13e80 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
13e90 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
13ea0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
13eb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
13ec0 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
13ed0 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
13ee0 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
13ef0 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
13f00 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
13f10 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
13f20 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  L then the alter
13f30 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
13f40 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
13f50 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
13f60 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
13f70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13f80 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
13f90 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
13fa0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
13fb0 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
13fc0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
13fd0 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
13fe0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
13ff0 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
14000 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
14010 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
14020 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
14030 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
14040 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
14050 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
14060 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
14070 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
14080 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
14090 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
140a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
140b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
140c0 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
140d0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
140e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
140f0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14100 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14110 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69  hich is a.** poi
14120 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14130 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
14140 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14150 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
14160 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
14170 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74  ecifies alternat
14180 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
14190 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
141a0 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c  be used.** in pl
141b0 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f  ace the mutex ro
141c0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
141d0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
141e0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
141f0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
14200 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
14210 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14220 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
14230 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
14240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
14250 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
14260 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14270 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
14280 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
14290 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
142a0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
142b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
142c0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
142d0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
142e0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
142f0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
14300 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
14310 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14320 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
14330 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14340 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
14350 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
14360 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
14370 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
14380 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14390 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
143a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
143b0 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
143c0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
143d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
143e0 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
143f0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14400 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14410 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14420 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14430 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
14440 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14450 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
14460 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14470 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
14480 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
14490 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
144a0 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
144b0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
144c0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
144d0 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
144e0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
144f0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
14500 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
14510 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
14520 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
14530 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
14540 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
14550 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
14560 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
14570 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14580 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14590 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
145a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
145b0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
145c0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
145d0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
145e0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
145f0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
14600 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
14610 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
14620 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14630 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
14640 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
14650 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
14660 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
14670 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
14680 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
14690 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
146a0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
146b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
146c0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
146d0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
146e0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
146f0 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  IDE option takes
14700 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
14710 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hat determine.**
14720 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a   the default siz
14730 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  e of lookaside m
14740 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64  emory on each [d
14750 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14760 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
14770 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
14780 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
14790 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
147a0 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
147b0 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
147c0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
147d0 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
147e0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
147f0 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c  ection.)^  ^(SQL
14800 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14810 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65  SIDE.** sets the
14820 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
14830 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
14840 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
14850 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
14860 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71  ** option to [sq
14870 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14880 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
14890 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
148a0 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
148b0 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
148c0 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
148d0 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
148e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
148f0 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
14900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14910 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14920 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14930 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
14940 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14950 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14960 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
14970 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
14980 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
14990 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
149a0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
149b0 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66  es.** the interf
149c0 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  ace to a custom 
149d0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
149e0 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  mentation.)^.** 
149f0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
14a00 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
14a10 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14a20 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64  ods2] object.</d
14a30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14a40 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14a50 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
14a60 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14a70 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
14a80 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14a90 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f  FIG_GETPCACHE2 o
14aa0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14ab0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14ac0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
14ad0 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
14ae0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
14af0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
14b00 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a  ite copies of.**
14b10 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67   the current pag
14b20 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
14b30 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
14b40 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
14b50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14b60 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
14b70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
14b80 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
14b90 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14ba0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20  G_LOG option is 
14bb0 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
14bc0 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  e the SQLite.** 
14bd0 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f  global [error lo
14be0 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c  g]..** (^The SQL
14bf0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
14c00 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
14c10 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
14c20 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
14c30 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
14c40 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
14c50 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
14c60 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
14c70 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
14c80 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
14c90 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
14ca0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
14cb0 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
14cc0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
14cd0 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
14ce0 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
14cf0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
14d00 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
14d10 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
14d20 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
14d30 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
14d40 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
14d50 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
14d60 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
14d70 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
14d80 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
14d90 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
14da0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
14db0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
14dc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
14dd0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
14de0 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
14df0 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
14e00 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
14e10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14e20 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
14e30 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
14e40 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
14e50 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14e60 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
14e70 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
14e80 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
14e90 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
14ea0 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
14eb0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
14ec0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
14ed0 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
14ee0 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
14ef0 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
14f00 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
14f10 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
14f20 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
14f30 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
14f40 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
14f50 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
14f60 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
14f70 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
14f80 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
14f90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
14fa0 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
14fb0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
14fc0 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
14fd0 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
14fe0 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
14ff0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15000 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
15010 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
15020 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
15030 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15040 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
15050 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
15060 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49  * <dd>^(The SQLI
15070 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70  TE_CONFIG_URI op
15080 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15090 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
150a0 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20  type int..** If 
150b0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55  non-zero, then U
150c0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
150d0 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e  lobally enabled.
150e0 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
150f0 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68  r is zero,.** th
15100 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
15110 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
15120 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20  bled.)^ ^If URI 
15130 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
15140 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c  ally.** enabled,
15150 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70   all filenames p
15160 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
15170 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
15180 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a  te3_open_v2()],.
15190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
151a0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
151b0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
151c0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
151d0 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
151e0 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
151f0 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
15200 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
15210 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
15220 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
15230 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
15240 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
15250 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
15260 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
15270 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
15280 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
15290 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
152a0 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
152b0 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
152c0 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
152d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
152e0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
152f0 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
15300 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
15310 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
15320 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
15330 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
15340 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
15350 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
15360 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
15370 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
15380 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15390 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
153a0 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
153b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
153c0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
153d0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
153e0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
153f0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f  ING_INDEX_SCAN o
15400 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15410 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20  ngle integer.** 
15420 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
15430 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
15440 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
15450 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
15460 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
15470 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
15480 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
15490 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
154a0 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
154b0 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  zer..** ^The def
154c0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20  ault setting is 
154d0 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79  determined.** by
154e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c   the [SQLITE_ALL
154f0 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  OW_COVERING_INDE
15500 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d  X_SCAN] compile-
15510 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20  time option, or 
15520 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68  is "on".** if th
15530 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
15540 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  option is omitte
15550 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74  d..** The abilit
15560 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  y to disable the
15570 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
15580 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
15590 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a  l table scans.**
155a0 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65   is because some
155b0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64   incorrectly cod
155c0 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63  ed legacy applic
155d0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c  ations might mal
155e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e  function.** when
155f0 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
15600 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50  n is enabled.  P
15610 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69  roviding the abi
15620 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62  lity to.** disab
15630 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  le the optimizat
15640 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f  ion allows the o
15650 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c  lder, buggy appl
15660 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20  ication code to 
15670 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20  work.** without 
15680 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68  change even with
15690 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
156a0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
156b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
156c0 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49  _PCACHE]] [[SQLI
156d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
156e0 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  CHE]].** <dt>SQL
156f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15700 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e  E and SQLITE_CON
15710 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  FIG_GETPCACHE.**
15720 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
15730 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
15740 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
15750 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
15760 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
15770 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
15780 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
15790 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
157a0 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
157b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
157c0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d  E_CONFIG_SQLLOG]
157d0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
157e0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a  CONFIG_SQLLOG.**
157f0 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
15800 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
15810 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20  le if sqlite is 
15820 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
15830 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
15840 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d  BLE_SQLLOG] pre-
15850 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
15860 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72  defined. The fir
15870 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  st argument shou
15880 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74  ld.** be a point
15890 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  er to a function
158a0 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29   of type void(*)
158b0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
158c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
158d0 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
158e0 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79   should be of ty
158f0 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20  pe (void*). The 
15900 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
15910 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61  ked by the libra
15920 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73  ry.** in three s
15930 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74  eparate circumst
15940 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65  ances, identifie
15950 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70  d by the value p
15960 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
15970 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15980 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  . If the fourth 
15990 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20  parameter is 0, 
159a0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
159b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
159c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
159d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61  cond argument ha
159e0 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e  s just been open
159f0 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  ed. The third ar
15a00 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73  gument.** points
15a10 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e   to a buffer con
15a20 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65  taining the name
15a30 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74   of the main dat
15a40 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74  abase file. If t
15a50 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
15a60 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65  ameter is 1, the
15a70 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
15a80 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69  ent that the thi
15a90 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
15aa0 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75  points to has ju
15ab0 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64  st been executed
15ac0 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75  . Or, if the fou
15ad0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
15ae0 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   2, then.** the 
15af0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67  connection being
15b00 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
15b10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15b20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e  is being closed.
15b30 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   The.** third pa
15b40 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65  rameter is passe
15b50 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63  d NULL In this c
15b60 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ase.  An example
15b70 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a   of using this.*
15b80 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
15b90 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65  option can be se
15ba0 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f  en in the "test_
15bb0 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65  sqllog.c" source
15bc0 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20   file in.** the 
15bd0 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65  canonical SQLite
15be0 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64   source tree.</d
15bf0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15c00 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15c10 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
15c20 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
15c30 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49  IZE.** <dd>^SQLI
15c40 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
15c50 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
15c60 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
15c70 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
15c80 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
15c90 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
15ca0 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
15cb0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
15cc0 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
15cd0 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
15ce0 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
15cf0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
15d00 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  mit..** ^The def
15d10 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e  ault setting can
15d20 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62   be overridden b
15d30 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  y each database 
15d40 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
15d50 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b  .** either the [
15d60 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
15d70 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79  ] command, or by
15d80 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
15d90 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
15da0 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
15db0 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69  rol.  ^(The maxi
15dc0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
15dd0 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65   size.** will be
15de0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
15df0 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79  ted if necessary
15e00 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73   so that it does
15e10 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a   not exceed the.
15e20 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
15e30 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a  maximum mmap siz
15e40 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  e set by the.** 
15e50 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50  [SQLITE_MAX_MMAP
15e60 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SIZE] compile-t
15e70 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a  ime option.)^.**
15e80 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75   ^If either argu
15e90 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74  ment to this opt
15ea0 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ion is negative,
15eb0 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d   then that argum
15ec0 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65  ent is.** change
15ed0 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65  d to its compile
15ee0 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a  -time default..*
15ef0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15f00 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15f10 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
15f20 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15f30 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64  _HEAPSIZE.** <dd
15f40 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
15f50 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15f60 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  ZE option is onl
15f70 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
15f80 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
15f90 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73  iled for Windows
15fa0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
15fb0 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20  E_WIN32_MALLOC] 
15fc0 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
15fd0 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20  cro.** defined. 
15fe0 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  ^SQLITE_CONFIG_W
15ff0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
16000 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
16010 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
16020 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
16030 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
16040 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
16050 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a  eated heap..**.*
16060 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16070 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d  G_PCACHE_HDRSZ]]
16080 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16090 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
160a0 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
160b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
160c0 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e  CHE_HDRSZ option
160d0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
160e0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
160f0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
16100 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
16110 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68  d writes into th
16120 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e  at integer the n
16130 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a  umber of extra.*
16140 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65  * bytes per page
16150 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61   required for ea
16160 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49  ch page in [SQLI
16170 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
16180 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f  CHE]..** The amo
16190 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61  unt of extra spa
161a0 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20  ce required can 
161b0 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67  change depending
161c0 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72   on the compiler
161d0 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74  ,.** target plat
161e0 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65  form, and SQLite
161f0 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20   version..**.** 
16200 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16210 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PMASZ]].** <dt>S
16220 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16230 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
16240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16250 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
16260 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
16270 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
16280 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  n unsigned integ
16290 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20  er and sets the 
162a0 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a  "Minimum PMA Siz
162b0 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69  e" for the multi
162c0 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74  threaded.** sort
162d0 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67  er to that integ
162e0 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  er.  The default
162f0 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a   minimum PMA Siz
16300 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a  e is set by the.
16310 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45  ** [SQLITE_SORTE
16320 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65  R_PMASZ] compile
16330 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e  -time option.  N
16340 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c  ew threads are l
16350 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65  aunched.** to he
16360 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65  lp with sort ope
16370 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c  rations when mul
16380 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69  tithreaded sorti
16390 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64  ng.** is enabled
163a0 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41   (using the [PRA
163b0 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d  GMA threads] com
163c0 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d  mand) and the am
163d0 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a  ount of content.
163e0 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20  ** to be sorted 
163f0 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65  exceeds the page
16400 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20   size times the 
16410 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a  minimum of the.*
16420 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f  * [PRAGMA cache_
16430 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e  size] setting an
16440 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a  d this value..**
16450 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
16460 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16470 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
16480 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16490 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
164a0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
164b0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
164c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
164d0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
164e0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
164f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16500 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
16510 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
16520 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
16530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16540 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
16550 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
16560 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
16570 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16580 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
16590 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
165a0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
165b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
165c0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
165d0 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
165e0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
165f0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
16600 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
16610 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
16620 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
16630 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
16640 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16650 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
16660 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
16670 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16680 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
16690 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
166a0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
166b0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
166c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
166d0 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
166e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
166f0 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
16700 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
16710 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
16720 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
16730 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
16740 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16750 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
16760 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
16770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16780 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
16790 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
167a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
167b0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
167c0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
167d0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
167e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
167f0 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
16800 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
16810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16820 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
16830 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
16840 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16850 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
16860 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
16870 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
16880 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
16890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
168a0 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
168b0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
168c0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
168d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
168e0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
168f0 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
16900 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
16910 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
16920 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
16930 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
16940 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16950 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
16960 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
16970 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
16980 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
16990 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
169a0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
169b0 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
169c0 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
169d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
169e0 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20  PCACHE_HDRSZ    
169f0 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a      24  /* int *
16a00 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  psz */.#define S
16a10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16a20 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  SZ              
16a30 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64   25  /* unsigned
16a40 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f   int szPma */../
16a50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
16a60 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
16a70 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
16a80 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
16a90 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
16aa0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
16ab0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
16ac0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
16ad0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
16ae0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
16af0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
16b00 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
16b10 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
16b20 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
16b30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16b40 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
16b50 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
16b60 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
16b70 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
16b80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
16b90 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
16ba0 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
16bb0 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
16bc0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
16bd0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
16be0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
16bf0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
16c00 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
16c10 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
16c20 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16c30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
16c40 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
16c50 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
16c60 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
16c70 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
16c80 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
16c90 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
16ca0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
16cb0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
16cc0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
16cd0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
16ce0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
16cf0 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
16d00 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
16d10 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
16d20 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
16d30 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
16d40 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
16d50 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
16d60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
16d70 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
16d80 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
16d90 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
16da0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16db0 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
16dc0 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
16dd0 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
16de0 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
16df0 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
16e00 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
16e10 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
16e20 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16e30 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
16e40 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
16e50 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
16e60 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
16e70 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
16e80 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
16e90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
16ea0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
16eb0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
16ec0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
16ed0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
16ee0 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
16ef0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
16f00 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
16f10 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
16f20 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
16f30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16f40 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
16f50 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
16f60 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
16f70 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
16f80 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
16f90 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
16fa0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
16fb0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
16fc0 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
16fd0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
16fe0 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
16ff0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17000 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
17010 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
17020 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
17030 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
17040 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
17050 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
17060 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
17070 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
17080 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
17090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
170a0 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
170b0 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
170c0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
170d0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
170e0 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
170f0 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
17100 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
17110 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
17120 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
17130 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
17140 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
17150 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
17160 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
17170 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
17180 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
17190 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
171a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
171b0 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
171c0 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
171d0 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
171e0 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
171f0 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
17200 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
17210 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
17220 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17230 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
17240 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
17250 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
17260 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
17270 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
17280 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
17290 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
172a0 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
172b0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
172c0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
172d0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
172e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
172f0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
17300 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
17310 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
17320 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17330 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
17340 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
17350 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
17360 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
17370 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
17380 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17390 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
173a0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
173b0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
173c0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
173d0 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
173e0 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
173f0 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
17400 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
17410 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17420 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
17430 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
17440 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
17450 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
17460 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
17470 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
17480 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
17490 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
174a0 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
174b0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
174c0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
174d0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
174e0 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
174f0 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
17500 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
17510 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
17520 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
17530 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
17540 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
17550 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
17560 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
17570 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
17580 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
17590 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
175a0 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
175b0 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
175c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
175d0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
175e0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
175f0 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
17600 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
17610 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
17620 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
17630 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
17640 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
17650 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
17660 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17670 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
17680 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
17690 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
176a0 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
176b0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
176c0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
176d0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
176e0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
176f0 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a  TOKENIZER</dt>.*
17700 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17710 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
17720 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
17730 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e   the two-argumen
17740 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  t.** version of 
17750 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69  the [fts3_tokeni
17760 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  zer()] function 
17770 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66  which is part of
17780 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66   the.** [FTS3] f
17790 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20  ull-text search 
177a0 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e  engine extension
177b0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
177c0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
177d0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
177e0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
177f0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
17800 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
17810 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f   disable fts3_to
17820 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20  kenizer() or.** 
17830 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
17840 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  le fts3_tokenize
17850 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20  r() or negative 
17860 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
17870 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ting.** unchange
17880 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
17890 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
178a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
178b0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
178c0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
178d0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
178e0 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74  e whether fts3_t
178f0 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61  okenizer is disa
17900 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
17910 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
17920 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
17930 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
17940 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
17950 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
17960 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65   case the new se
17970 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
17980 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
17990 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
179a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
179b0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
179c0 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31  DE             1
179d0 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  001 /* void* int
179e0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
179f0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17a00 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
17a10 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e        1002 /* in
17a20 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
17a30 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
17a40 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
17a50 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20          1003 /* 
17a60 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
17a70 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
17a80 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
17a90 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f  TOKENIZER 1004 /
17aa0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
17ab0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17ac0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
17ad0 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
17ae0 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f  t Codes.** METHO
17af0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
17b00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
17b10 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
17b20 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
17b30 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
17b40 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
17b50 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
17b60 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
17b70 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
17b80 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
17b90 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
17ba0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
17bb0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
17bc0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
17bd0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
17be0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
17bf0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
17c00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17c10 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
17c20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Rowid.** METHOD:
17c30 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
17c40 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
17c50 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
17c60 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
17c70 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
17c80 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
17c90 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
17ca0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
17cb0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
17cc0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
17cd0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
17ce0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
17cf0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
17d00 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
17d10 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
17d20 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
17d30 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
17d40 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
17d50 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
17d60 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
17d70 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
17d80 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
17d90 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
17da0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
17db0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
17dc0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
17dd0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
17de0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
17df0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17e00 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
17e10 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
17e20 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
17e30 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
17e40 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
17e50 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
17e60 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
17e70 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
17e80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17e90 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72  ion D..** ^Inser
17ea0 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
17eb0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
17ec0 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e  re not recorded.
17ed0 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
17ee0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
17ef0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
17f00 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
17f10 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64  ccurred on the d
17f20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17f30 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73  on D, .** then s
17f40 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17f50 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
17f60 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
17f70 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
17f80 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
17f90 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
17fa0 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
17fb0 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
17fc0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
17fd0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
17fe0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
17ff0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
18000 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
18010 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
18020 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
18030 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
18040 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
18050 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
18060 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
18070 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
18080 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
18090 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
180a0 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
180b0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
180c0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
180d0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
180e0 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
180f0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
18100 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
18110 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
18120 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
18130 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
18140 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
18150 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
18160 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
18170 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
18180 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
18190 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
181a0 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
181b0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
181c0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
181d0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
181e0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
181f0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
18200 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
18210 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
18220 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
18230 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
18240 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
18250 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
18260 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
18270 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
18280 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
18290 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
182a0 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
182b0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
182c0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
182d0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
182e0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
182f0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
18300 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
18310 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
18320 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
18330 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
18340 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
18350 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
18360 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
18370 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
18380 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
18390 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
183a0 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
183b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
183c0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
183d0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
183e0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
183f0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
18400 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
18410 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
18420 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
18430 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
18440 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
18450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18460 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
18470 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18480 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
18490 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
184a0 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
184b0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
184c0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
184d0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
184e0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
184f0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
18500 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
18510 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
18520 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
18530 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
18540 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
18550 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
18560 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
18570 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
18580 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
18590 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
185a0 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
185b0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
185c0 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
185d0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
185e0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
185f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
18600 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
18610 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  fied, inserted o
18620 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
18630 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
18640 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
18650 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
18660 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
18670 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  t on the databas
18680 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
18690 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e  cified by the on
186a0 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ly parameter..**
186b0 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
186c0 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
186d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
186e0 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
186f0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
18700 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
18710 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  on..**.** ^Only 
18720 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72  changes made dir
18730 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53  ectly by the INS
18740 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
18750 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
18760 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
18770 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68  d - auxiliary ch
18780 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
18790 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
187a0 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a  | triggers], .**
187b0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
187c0 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41  tions] or [REPLA
187d0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
187e0 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f  esolution are no
187f0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
18800 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
18810 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
18820 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20  ercepted by .** 
18830 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
18840 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46  ger | INSTEAD OF
18850 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e   triggers] are n
18860 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65  ot counted. ^The
18870 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72   value .** retur
18880 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
18890 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61  hanges() immedia
188a0 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e  tely after an IN
188b0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
188c0 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
188d0 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69  ment run on a vi
188e0 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  ew is always zer
188f0 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  o. Only changes 
18900 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a  made to real .**
18910 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e   tables are coun
18920 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67  ted..**.** Thing
18930 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  s are more compl
18940 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71  icated if the sq
18950 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
18960 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65  function is.** e
18970 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20  xecuted while a 
18980 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
18990 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73  is running. This
189a0 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74   may happen if t
189b0 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  he.** program us
189c0 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  es the [changes(
189d0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c  ) SQL function],
189e0 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65   or if some othe
189f0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  r callback.** fu
18a00 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73  nction invokes s
18a10 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
18a20 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e   directly. Essen
18a30 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c  tially:.** .** <
18a40 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ul>.**   <li> ^(
18a50 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20  Before entering 
18a60 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
18a70 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  m the value retu
18a80 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
18a90 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65    sqlite3_change
18aa0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  s() function is 
18ab0 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65  saved. After the
18ac0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
18ad0 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20   .**        has 
18ae0 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72  finished, the or
18af0 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20  iginal value is 
18b00 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a  restored.)^.** .
18b10 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68  **   <li> ^(With
18b20 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  in a trigger pro
18b30 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54  gram each INSERT
18b40 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c  , UPDATE and DEL
18b50 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73  ETE .**        s
18b60 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68  tatement sets th
18b70 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18b80 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
18b90 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
18ba0 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e   upon completion
18bb0 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63   as normal. Of c
18bc0 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75  ourse, this valu
18bd0 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75  e will not inclu
18be0 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e  de .**        an
18bf0 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72  y changes perfor
18c00 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67  med by sub-trigg
18c10 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69  ers, as the sqli
18c20 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
18c30 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77  *        value w
18c40 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64  ill be saved and
18c50 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20   restored after 
18c60 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72  each sub-trigger
18c70 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c   has run.)^.** <
18c80 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69  /ul>.** .** ^Thi
18c90 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  s means that if 
18ca0 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51  the changes() SQ
18cb0 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73  L function (or s
18cc0 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a  imilar) is used.
18cd0 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
18ce0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
18cf0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
18d00 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
18d10 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75  ger, it .** retu
18d20 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73  rns the value as
18d30 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61   set when the ca
18d40 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  lling statement 
18d50 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e  began executing.
18d60 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73  .** ^If it is us
18d70 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
18d80 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73   or subsequent s
18d90 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69  uch statement wi
18da0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a  thin a trigger .
18db0 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20  ** program, the 
18dc0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72  value returned r
18dd0 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62  eflects the numb
18de0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
18df0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70  ied by the .** p
18e00 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20  revious INSERT, 
18e10 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
18e20 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
18e30 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  n the same trigg
18e40 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
18e50 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
18e60 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
18e70 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
18e80 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
18e90 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
18ea0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
18eb0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
18ec0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
18ed0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
18ee0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
18ef0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18f00 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
18f10 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18f20 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
18f30 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
18f40 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
18f50 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
18f60 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
18f70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
18f80 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
18f90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18fa0 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
18fb0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
18fc0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
18fd0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
18fe0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
18ff0 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
19000 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64  of rows inserted
19010 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a  , modified or.**
19020 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20   deleted by all 
19030 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
19040 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
19050 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65  tatements comple
19060 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ted.** since the
19070 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19080 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c  tion was opened,
19090 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65   including those
190a0 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20   executed as.** 
190b0 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20  part of trigger 
190c0 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75  programs. ^Execu
190d0 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
190e0 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
190f0 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ment.** does not
19100 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75   affect the valu
19110 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
19120 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
19130 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43  ges()..** .** ^C
19140 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70  hanges made as p
19150 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20  art of [foreign 
19160 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
19170 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
19180 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74  .** count, but t
19190 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72  hose made as par
191a0 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  t of REPLACE con
191b0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
191c0 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e  on are.** not. ^
191d0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
191e0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
191f0 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41  cepted by INSTEA
19200 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a  D OF triggers .*
19210 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
19220 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c  d..** .** See al
19230 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
19240 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
19250 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
19260 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
19270 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
19280 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
19290 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
192a0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
192b0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
192c0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
192d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
192e0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
192f0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
19300 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
19310 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
19320 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
19330 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
19340 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
19350 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
19360 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
19370 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19380 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
19390 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
193a0 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d  nning Query.** M
193b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
193c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
193d0 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
193e0 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
193f0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
19400 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
19410 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
19420 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
19430 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
19440 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
19450 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
19460 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
19470 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
19480 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
19490 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
194a0 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
194b0 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
194c0 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
194d0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
194e0 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
194f0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
19500 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
19510 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
19520 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
19530 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
19540 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
19550 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
19560 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
19570 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
19580 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
19590 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
195a0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
195b0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
195c0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
195d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
195e0 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
195f0 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
19600 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
19610 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
19620 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
19630 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
19640 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
19650 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
19660 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
19670 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
19680 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
19690 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
196a0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
196b0 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
196c0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
196d0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
196e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
196f0 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
19700 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
19710 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
19720 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
19730 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
19740 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
19750 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
19760 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
19770 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
19780 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
19790 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
197a0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
197b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
197c0 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
197d0 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
197e0 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
197f0 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
19800 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
19810 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19820 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
19830 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
19840 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
19850 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
19860 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
19870 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
19880 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
19890 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
198a0 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
198b0 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
198c0 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
198d0 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
198e0 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
198f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
19900 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
19910 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
19920 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
19930 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
19940 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
19950 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
19960 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
19970 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
19980 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19990 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
199a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
199b0 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
199c0 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
199d0 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
199e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
199f0 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
19a00 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
19a10 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
19a20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
19a30 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
19a40 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
19a50 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
19a60 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
19a70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
19a80 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
19a90 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
19aa0 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
19ab0 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
19ac0 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
19ad0 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
19ae0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
19af0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
19b00 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
19b10 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
19b20 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
19b30 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
19b40 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
19b50 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
19b60 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
19b70 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
19b80 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
19b90 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
19ba0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
19bb0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
19bc0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
19bd0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
19be0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
19bf0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
19c00 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
19c10 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
19c20 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
19c30 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
19c40 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
19c50 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
19c60 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
19c70 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
19c80 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
19c90 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
19ca0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
19cb0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
19cc0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
19cd0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
19ce0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
19cf0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
19d00 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
19d10 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
19d20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
19d30 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
19d40 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
19d50 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
19d60 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
19d70 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
19d80 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
19d90 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
19da0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
19db0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
19dc0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
19dd0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
19de0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
19df0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
19e00 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
19e10 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
19e20 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
19e30 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
19e40 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
19e50 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
19e60 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
19e70 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
19e80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
19e90 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
19ea0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
19eb0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
19ec0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
19ed0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
19ee0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
19ef0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
19f00 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
19f10 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
19f20 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
19f30 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
19f40 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
19f50 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
19f60 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
19f70 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
19f80 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19f90 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
19fa0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
19fb0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
19fc0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
19fd0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
19fe0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
19ff0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1a000 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1a010 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1a020 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1a030 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1a040 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1a050 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1a060 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1a070 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1a080 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1a090 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1a0a0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1a0b0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1a0c0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1a0d0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1a0e0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1a0f0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1a100 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1a110 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1a120 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1a130 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1a140 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1a150 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
1a160 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
1a170 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1a180 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
1a190 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1a1a0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
1a1b0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
1a1c0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
1a1d0 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  rrors.** KEYWORD
1a1e0 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72  S: {busy-handler
1a1f0 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79   callback} {busy
1a200 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54   handler}.** MET
1a210 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1a220 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a230 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
1a240 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
1a250 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1a260 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
1a270 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1a280 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
1a290 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1a2a0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1a2b0 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
1a2c0 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
1a2d0 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
1a2e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a2f0 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
1a300 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
1a310 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
1a320 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
1a330 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1a340 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
1a350 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
1a360 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
1a370 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1a380 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
1a390 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
1a3a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
1a3b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1a3c0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
1a3d0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
1a3e0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1a3f0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
1a400 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
1a410 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1a420 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
1a430 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1a440 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
1a450 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
1a460 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
1a470 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1a480 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
1a490 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
1a4a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
1a4b0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
1a4c0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
1a4d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1a4e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a4f0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
1a500 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1a510 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1a520 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1a530 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
1a540 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
1a550 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
1a560 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76  een invoked prev
1a570 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73  iously for the s
1a580 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
1a590 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1a5a0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1a5b0 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1a5c0 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1a5d0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1a5e0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1a5f0 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1a600 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75  TE_BUSY] is retu
1a610 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61  rned.** to the a
1a620 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  pplication..** ^
1a630 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1a640 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1a650 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1a660 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1a670 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  e to access the 
1a680 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
1a690 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
1a6a0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
1a6b0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
1a6c0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
1a6d0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
1a6e0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
1a6f0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
1a700 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
1a710 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
1a720 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
1a730 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
1a740 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
1a750 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
1a760 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
1a770 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
1a780 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1a790 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1a7a0 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66  ation instead of
1a7b0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a   invoking the .*
1a7c0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
1a7d0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1a7e0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1a7f0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1a800 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1a810 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1a820 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1a830 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1a840 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1a850 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1a860 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1a870 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1a880 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1a890 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1a8a0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1a8b0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1a8c0 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1a8d0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1a8e0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1a8f0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1a900 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1a910 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1a920 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1a930 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1a940 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1a950 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1a960 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1a970 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1a980 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1a990 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1a9a0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1a9b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1a9c0 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1a9d0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1a9e0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1a9f0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1aa00 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1aa10 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1aa20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1aa30 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1aa40 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1aa50 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1aa60 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1aa70 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  NULL..**.** ^(Th
1aa80 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1aa90 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1aaa0 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
1aab0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
1aac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1aad0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
1aae0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
1aaf0 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
1ab00 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
1ab10 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
1ab20 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1ab30 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1ab40 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69  ].** or evaluati
1ab50 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  ng [PRAGMA busy_
1ab60 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20  timeout=N] will 
1ab70 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75  change the.** bu
1ab80 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74  sy handler and t
1ab90 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72  hus clear any pr
1aba0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73  eviously set bus
1abb0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1abc0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1abd0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1abe0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1abf0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1ac00 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1ac10 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1ac20 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1ac30 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  dler.  In other 
1ac40 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75  words,.** the bu
1ac50 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f  sy handler is no
1ac60 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e  t reentrant.  An
1ac70 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1ac80 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1ac90 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1aca0 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1acb0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1acc0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1acd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1ace0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1acf0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1ad00 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1ad10 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
1ad20 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1ad30 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1ad40 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
1ad50 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1ad60 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
1ad70 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d  usy Timeout.** M
1ad80 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1ad90 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1ada0 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
1adb0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
1adc0 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
1add0 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
1ade0 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
1adf0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
1ae00 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
1ae10 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
1ae20 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
1ae30 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
1ae40 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
1ae50 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1ae60 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
1ae70 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
1ae80 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
1ae90 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1aea0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1aeb0 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
1aec0 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
1aed0 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
1aee0 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
1aef0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
1af00 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  USY]..**.** ^Cal
1af10 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
1af20 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
1af30 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
1af40 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
1af50 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
1af60 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
1af70 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1af80 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1af90 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
1afa0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
1afb0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1afc0 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67  ection] at any g
1afd0 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
1afe0 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
1aff0 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
1b000 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
1b010 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1b020 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
1b030 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
1b040 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
1b050 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1b060 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
1b070 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
1b080 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1b090 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  eout].*/.int sql
1b0a0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1b0b0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1b0c0 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
1b0d0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
1b0e0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
1b0f0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
1b100 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1b110 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  3.**.** This is 
1b120 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
1b130 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
1b140 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
1b150 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1b160 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
1b170 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
1b180 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
1b190 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
1b1a0 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
1b1b0 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
1b1c0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
1b1d0 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
1b1e0 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
1b1f0 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
1b200 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
1b210 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
1b220 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
1b230 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
1b240 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
1b250 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
1b260 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
1b270 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
1b280 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
1b290 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
1b2a0 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
1b2b0 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
1b2c0 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
1b2d0 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
1b2e0 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
1b2f0 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
1b300 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
1b310 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
1b320 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
1b330 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
1b340 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1b350 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
1b360 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
1b370 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1b380 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
1b390 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
1b3a0 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
1b3b0 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
1b3c0 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
1b3d0 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
1b3e0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1b3f0 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
1b400 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
1b410 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
1b420 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
1b430 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
1b440 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
1b450 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
1b460 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
1b470 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
1b480 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
1b490 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
1b4a0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1b4b0 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
1b4c0 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
1b4d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
1b4e0 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
1b4f0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1b500 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
1b510 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
1b520 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1b530 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
1b540 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
1b550 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
1b560 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
1b570 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
1b580 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
1b590 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
1b5a0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1b5b0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
1b5c0 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
1b5d0 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
1b5e0 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
1b5f0 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
1b600 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
1b610 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1b620 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b630 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
1b640 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
1b650 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
1b660 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b670 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
1b680 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
1b690 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
1b6a0 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
1b6b0 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
1b6c0 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
1b6d0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1b6e0 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
1b6f0 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
1b700 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
1b710 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
1b720 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
1b730 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
1b740 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
1b750 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
1b760 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
1b770 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
1b780 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
1b790 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
1b7a0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b7b0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1b7c0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b7d0 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
1b7e0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b7f0 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
1b800 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b810 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
1b820 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
1b830 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
1b840 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
1b850 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
1b860 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
1b870 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b880 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
1b890 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b8a0 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
1b8b0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b8c0 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
1b8d0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1b8e0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1b8f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
1b900 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
1b910 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
1b920 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
1b930 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
1b940 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b950 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
1b960 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
1b970 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
1b980 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
1b990 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1b9a0 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
1b9b0 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
1b9c0 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
1b9d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
1b9e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1b9f0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1ba00 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
1ba10 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
1ba20 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
1ba30 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
1ba40 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
1ba50 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1ba60 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
1ba70 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
1ba80 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
1ba90 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
1baa0 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
1bab0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1bac0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
1bad0 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
1bae0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
1baf0 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
1bb00 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
1bb10 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
1bb20 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
1bb30 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
1bb40 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1bb50 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
1bb60 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
1bb70 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
1bb80 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
1bb90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1bba0 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
1bbb0 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
1bbc0 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
1bbd0 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
1bbe0 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
1bbf0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1bc00 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
1bc10 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
1bc20 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
1bc30 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
1bc40 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
1bc50 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
1bc60 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
1bc70 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
1bc80 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
1bc90 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
1bca0 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
1bcb0 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
1bcc0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
1bcd0 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
1bce0 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
1bcf0 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
1bd00 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
1bd10 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1bd20 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
1bd30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1bd40 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  msg()]..*/.int s
1bd50 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1bd60 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1bd70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1bd80 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1bd90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1bda0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1bdb0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1bdc0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1bdd0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1bde0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1bdf0 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1be00 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1be10 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1be20 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1be30 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1be40 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1be50 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1be60 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1be70 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1be80 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1be90 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1bea0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1beb0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1bec0 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
1bed0 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
1bee0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
1bef0 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
1bf00 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
1bf10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1bf20 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
1bf30 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
1bf40 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
1bf50 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
1bf60 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
1bf70 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68  C library..** Th
1bf80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64  ese routines und
1bf90 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20  erstand most of 
1bfa0 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66  the common K&R f
1bfb0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1bfc0 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20  s,.** plus some 
1bfd0 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73  additional non-s
1bfe0 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c  tandard formats,
1bff0 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e   detailed below.
1c000 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f  .** Note that so
1c010 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f  me of the more o
1c020 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e  bscure formattin
1c030 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72  g options from r
1c040 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61  ecent.** C-libra
1c050 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65  ry standards are
1c060 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
1c070 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  is implementatio
1c080 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
1c090 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1c0a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1c0b0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1c0c0 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1c0d0 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1c0e0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1c0f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1c100 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1c110 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1c120 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1c130 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1c140 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1c150 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1c160 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1c170 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1c180 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1c190 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
1c1a0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1c1b0 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1c1c0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1c1d0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1c1e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1c1f0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1c200 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1c210 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1c220 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1c230 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1c240 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1c250 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1c260 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1c270 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1c280 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1c290 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1c2a0 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1c2b0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1c2c0 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1c2d0 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1c2e0 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1c2f0 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1c300 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1c310 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1c320 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1c330 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1c340 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1c350 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1c360 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1c370 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1c380 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1c390 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1c3a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1c3b0 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1c3c0 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1c3d0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1c3e0 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1c3f0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1c400 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1c410 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1c420 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1c430 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1c440 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1c450 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1c460 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1c470 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1c480 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1c490 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1c4a0 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1c4b0 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1c4c0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1c4d0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1c4e0 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1c4f0 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1c500 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1c510 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1c520 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1c530 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1c540 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1c550 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1c560 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1c570 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1c580 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1c590 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
1c5a0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1c5b0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
1c5c0 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
1c5d0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
1c5e0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
1c5f0 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
1c600 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
1c610 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1c620 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1c630 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
1c640 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1c650 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
1c660 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
1c670 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
1c680 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
1c690 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
1c6a0 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
1c6b0 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
1c6c0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1c6d0 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
1c6e0 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
1c6f0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1c700 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
1c710 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
1c720 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
1c730 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a  Q", "%w" and "%z
1c740 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
1c750 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
1c760 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
1c770 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
1c780 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
1c790 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1c7a0 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
1c7b0 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
1c7c0 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
1c7d0 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
1c7e0 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
1c7f0 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
1c800 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
1c810 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
1c820 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
1c830 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
1c840 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
1c850 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
1c860 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
1c870 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
1c880 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
1c890 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
1c8a0 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
1c8b0 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
1c8c0 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
1c8d0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c8e0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c8f0 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
1c900 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
1c910 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
1c920 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c930 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
1c940 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
1c950 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
1c960 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c970 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c980 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1c990 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1c9a0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1c9b0 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
1c9c0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1c9d0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1c9e0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1c9f0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1ca00 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1ca10 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1ca20 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
1ca30 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
1ca40 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
1ca50 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
1ca60 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
1ca70 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
1ca80 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
1ca90 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1caa0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1cab0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1cac0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1cad0 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
1cae0 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
1caf0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1cb00 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
1cb10 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
1cb20 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
1cb30 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
1cb40 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
1cb50 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
1cb60 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
1cb70 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1cb80 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1cb90 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
1cba0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
1cbb0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1cbc0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1cbd0 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
1cbe0 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
1cbf0 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
1cc00 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
1cc10 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
1cc20 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
1cc30 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
1cc40 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
1cc50 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1cc60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
1cc70 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1cc80 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
1cc90 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
1cca0 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
1ccb0 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
1ccc0 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
1ccd0 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
1cce0 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
1ccf0 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
1cd00 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
1cd10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
1cd20 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
1cd30 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
1cd40 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
1cd50 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
1cd60 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
1cd70 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
1cd80 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1cd90 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1cda0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1cdb0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1cdc0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
1cdd0 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
1cde0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1cdf0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1ce00 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1ce10 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1ce20 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1ce30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
1ce40 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
1ce50 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
1ce60 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1ce70 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
1ce80 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
1ce90 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
1cea0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1ceb0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22  **.** ^(The "%w"
1cec0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1ced0 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20  on is like "%q" 
1cee0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65  except that it e
1cef0 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20  xpects to.** be 
1cf00 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
1cf10 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69   double-quotes i
1cf20 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65  nstead of single
1cf30 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a   quotes, and it.
1cf40 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64  ** escapes the d
1cf50 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72  ouble-quote char
1cf60 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  acter instead of
1cf70 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74   the single-quot
1cf80 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29  e.** character.)
1cf90 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d  ^  The "%w" form
1cfa0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73  atting option is
1cfb0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61   intended for sa
1cfc0 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a  fely inserting.*
1cfd0 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  * table and colu
1cfe0 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20  mn names into a 
1cff0 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20  constructed SQL 
1d000 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
1d010 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
1d020 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
1d030 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
1d040 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
1d050 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
1d060 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
1d070 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
1d080 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
1d090 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
1d0a0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
1d0b0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
1d0c0 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63  t string.)^.*/.c
1d0d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
1d0e0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1d0f0 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
1d100 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
1d110 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1d120 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
1d130 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
1d140 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1d150 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  *, ...);.char *s
1d160 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1d170 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1d180 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1d190 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d1a0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1d1b0 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
1d1c0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
1d1d0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
1d1e0 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
1d1f0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
1d200 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
1d210 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d220 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
1d230 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
1d240 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
1d250 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
1d260 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
1d270 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
1d280 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
1d290 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
1d2a0 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
1d2b0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
1d2c0 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
1d2d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d2e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
1d2f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
1d300 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
1d310 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
1d320 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1d330 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
1d340 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
1d350 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
1d360 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1d370 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
1d380 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
1d390 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
1d3a0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1d3b0 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
1d3c0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
1d3d0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1d3e0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
1d3f0 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
1d400 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
1d410 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
1d420 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1d430 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1d440 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20  oc64(N) routine 
1d450 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a  works just like.
1d460 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1d470 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  c(N) except that
1d480 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65   N is an unsigne
1d490 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  d 64-bit integer
1d4a0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1d4b0 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69   signed 32-bit i
1d4c0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  nteger..**.** ^C
1d4d0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
1d4e0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
1d4f0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
1d500 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1d510 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1d520 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1d530 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
1d540 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
1d550 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
1d560 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
1d570 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
1d580 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
1d590 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
1d5a0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1d5b0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
1d5c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
1d5d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1d5e0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
1d5f0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
1d600 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
1d610 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
1d620 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
1d630 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
1d640 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
1d650 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
1d660 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
1d670 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
1d680 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1d690 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
1d6a0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
1d6b0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1d6c0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
1d6d0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
1d6e0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
1d6f0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
1d700 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
1d710 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
1d720 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
1d730 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1d740 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1d750 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d770 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1d780 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1d790 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1d7a0 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1d7b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f   allocation X to
1d7c0 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
1d7d0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
1d7e0 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   X parameter to 
1d7f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d800 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  X,N).** is a NUL
1d810 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
1d820 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
1d830 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
1d840 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
1d850 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66  alloc(N)..** ^If
1d860 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
1d870 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1d880 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f  loc(X,N) is zero
1d890 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1d8a0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1d8b0 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1d8c0 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1d8d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1d8e0 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  (X)..** ^sqlite3
1d8f0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
1d900 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1d910 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
1d920 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
1d930 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1d940 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
1d950 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
1d960 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c  mory is availabl
1d970 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
1d980 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
1d990 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
1d9a0 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
1d9b0 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
1d9c0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1d9d0 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
1d9e0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1d9f0 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
1da00 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
1da10 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20  ealloc(X,N) and 
1da20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1da30 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
1da40 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
1da50 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1da60 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73  ns NULL and N is
1da70 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
1da80 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c  the.** prior all
1da90 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66  ocation is not f
1daa0 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  reed..**.** ^The
1dab0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1dac0 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  64(X,N) interfac
1dad0 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  es works the sam
1dae0 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e as.** sqlite3_
1daf0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63  realloc(X,N) exc
1db00 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20  ept that N is a 
1db10 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
1db20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1db30 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73  ** of a 32-bit s
1db40 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
1db50 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20  *.** ^If X is a 
1db60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1db70 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  n previously obt
1db80 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1db90 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  e3_malloc(),.** 
1dba0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1dbb0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
1dbc0 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  loc(), or sqlite
1dbd0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74  3_realloc64(), t
1dbe0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  hen.** sqlite3_m
1dbf0 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20  size(X) returns 
1dc00 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74  the size of that
1dc10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1dc20 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20  on in bytes..** 
1dc30 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1dc40 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1dc50 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65  size(X) might be
1dc60 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
1dc70 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79   number.** of by
1dc80 74 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68  tes requested wh
1dc90 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74  en X was allocat
1dca0 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20  ed.  ^If X is a 
1dcb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1dcc0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1dcd0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65  ze(X) returns ze
1dce0 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73  ro.  If X points
1dcf0 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68   to something th
1dd00 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65  at is not.** the
1dd10 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65   beginning of me
1dd20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  mory allocation,
1dd30 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73   or if it points
1dd40 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a   to a formerly.*
1dd50 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61  * valid memory a
1dd60 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68  llocation that h
1dd70 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65  as now been free
1dd80 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
1dd90 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  vior.** of sqlit
1dda0 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75  e3_msize(X) is u
1ddb0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73  ndefined and pos
1ddc0 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  sibly harmful..*
1ddd0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1dde0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1ddf0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73  ite3_malloc(), s
1de00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1de10 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1de20 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c  loc64(), and sql
1de30 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
1de40 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
1de50 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
1de60 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
1de70 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
1de80 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
1de90 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1dea0 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
1deb0 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
1dec0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
1ded0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
1dee0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1def0 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
1df00 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
1df10 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
1df20 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
1df30 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
1df40 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
1df50 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
1df60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1df70 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1df80 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
1df90 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
1dfa0 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
1dfb0 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
1dfc0 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
1dfd0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
1dfe0 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
1dff0 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
1e000 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20  version 3.7.10, 
1e010 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  the Windows OS i
1e020 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
1e030 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73  alled.** the sys
1e040 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
1e050 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
1e060 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
1e070 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
1e080 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
1e090 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
1e0a0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
1e0b0 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
1e0c0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
1e0d0 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
1e0e0 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
1e0f0 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
1e100 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1e110 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65  errors were dete
1e120 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
1e130 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20  y were reported 
1e140 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
1e150 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
1e160 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
1e170 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
1e180 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
1e190 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
1e1a0 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
1e1b0 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
1e1c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e1d0 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
1e1e0 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
1e1f0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
1e200 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
1e210 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
1e220 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1e230 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
1e240 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
1e250 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
1e260 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
1e270 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
1e280 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
1e290 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
1e2a0 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
1e2b0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
1e2c0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
1e2d0 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
1e2e0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
1e2f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1e300 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
1e310 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1e320 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
1e330 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1e340 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
1e350 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1e360 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1e370 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
1e380 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64  3_realloc64(void
1e390 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
1e3a0 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
1e3b0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71  _free(void*);.sq
1e3c0 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c  lite3_uint64 sql
1e3d0 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a  ite3_msize(void*
1e3e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e3f0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1e400 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
1e410 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
1e420 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
1e430 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
1e440 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
1e450 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
1e460 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e470 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
1e480 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
1e490 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1e4a0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
1e4b0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
1e4c0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1e4d0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
1e4e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
1e4f0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1e500 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1e510 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1e520 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
1e530 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
1e540 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
1e550 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
1e560 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
1e570 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e580 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
1e590 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
1e5a0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
1e5b0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
1e5c0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
1e5d0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1e5e0 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
1e5f0 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
1e600 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
1e610 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1e620 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1e630 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1e640 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
1e650 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
1e660 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
1e670 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
1e680 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
1e690 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1e6a0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
1e6b0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
1e6c0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
1e6d0 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
1e6e0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1e6f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e700 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
1e710 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1e720 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
1e730 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
1e740 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
1e750 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1e760 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
1e770 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
1e780 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
1e790 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1e7a0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
1e7b0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
1e7c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1e7d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1e7e0 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
1e7f0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1e800 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
1e810 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
1e820 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1e830 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1e840 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
1e850 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1e860 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1e870 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1e880 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e890 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1e8a0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1e8b0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1e8c0 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1e8d0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1e8e0 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1e8f0 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1e900 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1e910 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1e920 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1e930 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1e940 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1e950 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1e960 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1e970 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1e980 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1e990 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1e9a0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1e9b0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1e9c0 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1e9d0 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1e9e0 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1e9f0 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1ea00 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1ea10 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1ea20 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1ea30 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1ea40 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1ea50 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1ea60 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1ea70 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65  ** ^The P parame
1ea80 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c  ter can be a NUL
1ea90 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1eaa0 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e   ^If this routin
1eab0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70  e has not been p
1eac0 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64  reviously called
1ead0 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69   or if the previ
1eae0 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20  ous.** call had 
1eaf0 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  N less than one 
1eb00 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
1eb10 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68  r for P, then th
1eb20 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65  e PRNG is.** see
1eb30 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1eb40 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ness obtained fr
1eb50 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
1eb60 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20  ss method of.** 
1eb70 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1eb80 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1eb90 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65  ..** ^If the pre
1eba0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
1ebb0 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61  is routine had a
1ebc0 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65  n N of 1 or more
1ebd0 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55   and a.** non-NU
1ebe0 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73  LL P then the ps
1ebf0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
1ec00 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
1ec10 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
1ec20 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
1ec30 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1ec40 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
1ec50 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76  .** method..*/.v
1ec60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
1ec70 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
1ec80 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
1ec90 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
1eca0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
1ecb0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1ecc0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1ecd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1ece0 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
1ecf0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
1ed00 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
1ed10 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1ed20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1ed30 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
1ed40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1ed50 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
1ed60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1ed70 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
1ed80 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
1ed90 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
1eda0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
1edb0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1edc0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
1edd0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
1ede0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1edf0 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
1ee00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1ee10 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
1ee20 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
1ee30 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
1ee40 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
1ee50 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
1ee60 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
1ee70 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
1ee80 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
1ee90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1eea0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
1eeb0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
1eec0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
1eed0 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
1eee0 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
1eef0 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
1ef00 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
1ef10 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
1ef20 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
1ef30 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
1ef40 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
1ef50 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
1ef60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1ef70 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
1ef80 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
1ef90 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
1efa0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
1efb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1efc0 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
1efd0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
1efe0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1eff0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
1f000 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
1f010 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1f020 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
1f030 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
1f040 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
1f050 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
1f060 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1f070 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1f080 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1f090 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1f0a0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1f0b0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1f0c0 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
1f0d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1f0e0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
1f0f0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1f100 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
1f110 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
1f120 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1f130 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1f140 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
1f150 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f160 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1f170 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1f180 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
1f190 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1f1a0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1f1b0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
1f1c0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
1f1d0 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
1f1e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1f1f0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
1f200 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f210 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1f220 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
1f230 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1f240 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
1f250 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
1f260 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
1f270 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
1f280 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1f290 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
1f2a0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
1f2b0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
1f2c0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
1f2d0 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
1f2e0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1f2f0 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
1f300 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
1f310 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
1f320 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
1f330 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1f340 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
1f350 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
1f360 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
1f370 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
1f380 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
1f390 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1f3a0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1f3b0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
1f3c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1f3d0 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
1f3e0 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
1f3f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f400 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
1f410 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
1f420 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
1f430 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
1f440 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
1f450 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
1f460 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
1f470 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
1f480 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
1f490 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
1f4a0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
1f4b0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
1f4c0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
1f4d0 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
1f4e0 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
1f4f0 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
1f500 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
1f510 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1f520 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
1f530 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
1f540 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
1f550 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1f560 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
1f570 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
1f580 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
1f590 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
1f5a0 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
1f5b0 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
1f5c0 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
1f5d0 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
1f5e0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
1f5f0 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
1f600 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1f610 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
1f620 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
1f630 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
1f640 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
1f650 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
1f660 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
1f670 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
1f680 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
1f690 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
1f6a0 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
1f6b0 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
1f6c0 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
1f6d0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
1f6e0 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
1f6f0 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
1f700 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
1f710 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
1f720 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
1f730 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
1f740 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
1f750 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
1f760 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
1f770 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
1f780 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
1f790 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
1f7a0 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
1f7b0 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
1f7c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
1f7d0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
1f7e0 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
1f7f0 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
1f800 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
1f810 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
1f820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1f830 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
1f840 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
1f850 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
1f860 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1f870 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
1f880 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
1f890 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
1f8a0 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
1f8b0 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
1f8c0 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
1f8d0 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
1f8e0 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
1f8f0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
1f900 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
1f910 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
1f920 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
1f930 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1f940 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
1f950 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
1f960 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
1f970 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
1f980 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
1f990 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
1f9a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f9b0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
1f9c0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
1f9d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1f9e0 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
1f9f0 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
1fa00 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
1fa10 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
1fa20 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
1fa30 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
1fa40 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1fa50 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
1fa60 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
1fa70 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1fa80 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1fa90 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1faa0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1fab0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1fac0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1fad0 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
1fae0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
1faf0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1fb00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fb10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1fb20 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1fb30 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1fb40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fb50 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1fb60 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1fb70 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1fb80 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
1fb90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1fba0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
1fbb0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1fbc0 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
1fbd0 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
1fbe0 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
1fbf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1fc00 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
1fc10 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
1fc20 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
1fc30 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
1fc40 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1fc50 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
1fc60 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
1fc70 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
1fc80 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
1fc90 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
1fca0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
1fcb0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fcc0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
1fcd0 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
1fce0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1fcf0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1fd00 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
1fd10 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
1fd20 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
1fd30 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
1fd40 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
1fd50 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
1fd60 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
1fd70 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
1fd80 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
1fd90 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
1fda0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fdb0 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
1fdc0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
1fdd0 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
1fde0 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
1fdf0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1fe00 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
1fe10 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
1fe20 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
1fe30 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1fe40 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1fe50 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
1fe60 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
1fe70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fe80 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
1fe90 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1fea0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1feb0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1fec0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1fed0 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
1fee0 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
1fef0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
1ff00 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
1ff10 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
1ff20 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
1ff30 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
1ff40 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
1ff50 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
1ff60 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
1ff70 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1ff80 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1ff90 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
1ffa0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1ffb0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1ffc0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
1ffd0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61  LITE_IGNORE is a
1ffe0 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63  lso used as a [c
1fff0 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69  onflict resoluti
20000 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75  on mode].** retu
20010 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73  rned from the [s
20020 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63  qlite3_vtab_on_c
20030 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72  onflict()] inter
20040 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
20050 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
20060 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
20070 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
20080 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
20090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
200a0 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
200b0 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
200c0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
200d0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
200e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
200f0 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
20100 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
20110 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
20120 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
20130 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
20140 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
20150 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
20160 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
20170 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
20180 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
20190 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
201a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
201b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
201c0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
201d0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
201e0 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
201f0 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
20200 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
20210 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
20220 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
20230 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20240 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
20250 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
20260 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
20270 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
20280 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
20290 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
202a0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
202b0 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
202c0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
202d0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
202e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
202f0 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
20300 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
20310 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
20320 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
20330 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
20340 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
20350 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
20360 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
20370 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
20380 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
20390 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
203a0 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
203b0 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
203c0 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
203d0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
203e0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
203f0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
20400 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
20410 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
20420 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
20430 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
20440 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
20450 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
20460 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
20470 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
20480 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
20490 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
204a0 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
204b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
204c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
204d0 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
204e0 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
204f0 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
20500 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
20510 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
20520 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
20530 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20540 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20550 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
20560 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
20570 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
20580 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20590 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
205a0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
205b0 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
205c0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
205d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
205e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
205f0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
20600 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
20610 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
20620 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20640 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
20650 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
20660 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
20670 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
20690 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
206a0 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
206b0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
206c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
206d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
206e0 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
206f0 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
20700 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
20710 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20720 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20730 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
20740 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
20750 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
20760 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20770 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
20780 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
20790 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
207a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
207b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
207c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
207d0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
207e0 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
207f0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
20800 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
20810 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
20820 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
20830 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20840 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20850 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20860 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
20870 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
20880 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
20890 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
208a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
208b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
208c0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
208d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
208e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
208f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20900 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
20910 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
20920 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
20930 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20940 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20950 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
20960 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
20970 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
20980 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20990 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
209a0 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
209b0 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
209c0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
209d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
209e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
209f0 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
20a00 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
20a10 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
20a20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20a30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20a40 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
20a50 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
20a60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
20a70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20a80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20a90 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
20aa0 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
20ab0 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
20ac0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
20ad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20ae0 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
20af0 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
20b00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
20b10 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
20b20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
20b30 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
20b40 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
20b50 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
20b60 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20b70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
20b80 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
20b90 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
20ba0 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
20bb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20bc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
20bd0 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
20be0 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
20bf0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
20c00 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
20c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
20c20 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
20c30 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
20c40 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
20c50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20c60 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
20c70 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
20c80 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
20c90 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
20ca0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20cb0 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
20cc0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
20cd0 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
20ce0 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
20cf0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
20d00 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
20d10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
20d20 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
20d30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20d40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20d50 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
20d60 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
20d70 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20d80 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20d90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20da0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
20db0 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
20dc0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20dd0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
20de0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20df0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
20e00 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
20e10 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20e20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
20e30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20e40 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
20e50 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
20e60 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
20e70 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
20e80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20e90 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
20ea0 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
20eb0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
20ec0 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
20ed0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20ee0 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
20ef0 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
20f00 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
20f10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20f20 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20  _RECURSIVE      
20f30 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55        33   /* NU
20f40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
20f50 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20f60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20f70 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
20f80 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
20f90 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
20fa0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ite3.**.** These
20fb0 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
20fc0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
20fd0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
20fe0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
20ff0 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
21000 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
21010 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
21020 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
21030 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
21040 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
21050 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
21060 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
21070 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
21080 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
21090 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
210a0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
210b0 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
210c0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
210d0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
210e0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
210f0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
21100 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
21110 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
21120 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
21130 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
21140 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
21150 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
21160 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
21170 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
21180 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
21190 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
211a0 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
211b0 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
211c0 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
211d0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
211e0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
211f0 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
21200 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
21210 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
21220 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
21230 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
21240 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
21250 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
21260 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
21270 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
21280 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
21290 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
212a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
212b0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
212c0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
212d0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
212e0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
212f0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
21300 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
21310 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
21320 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
21330 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
21340 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
21350 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
21360 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
21370 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
21380 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
21390 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
213a0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
213b0 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
213c0 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
213d0 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
213e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
213f0 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
21400 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
21410 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
21420 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
21430 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
21440 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
21450 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
21460 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
21470 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
21480 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
21490 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
214a0 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
214b0 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
214c0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
214d0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
214e0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
214f0 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
21500 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
21510 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
21520 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
21530 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
21540 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
21550 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
21560 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
21570 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
21580 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
21590 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
215a0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
215b0 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
215c0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
215d0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
215e0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
215f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
21600 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
21610 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
21620 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
21630 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
21640 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
21650 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
21660 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
21670 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
21680 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
21690 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
216a0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
216b0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
216c0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
216d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
216e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
216f0 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
21700 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
21710 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
21720 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
21730 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
21740 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
21750 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
21760 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
21770 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
21780 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
21790 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
217a0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
217b0 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
217c0 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
217d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
217e0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
217f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
21800 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
21810 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
21820 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
21830 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
21840 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
21850 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
21860 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
21870 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
21880 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
21890 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
218a0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
218b0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
218c0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
218d0 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
218e0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
218f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
21900 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
21910 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
21920 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
21930 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
21940 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
21950 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
21960 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
21970 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
21980 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
21990 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
219a0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
219b0 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
219c0 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
219d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
219e0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
219f0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
21a00 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
21a10 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
21a20 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
21a30 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
21a40 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
21a50 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
21a60 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
21a70 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
21a80 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
21a90 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
21aa0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
21ab0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
21ac0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
21ad0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21ae0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
21af0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
21b00 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
21b10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21b20 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
21b30 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
21b40 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
21b50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21b60 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
21b70 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
21b80 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
21b90 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
21ba0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
21bb0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
21bc0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
21bd0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
21be0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21bf0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
21c00 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
21c10 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
21c20 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
21c30 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
21c40 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
21c50 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
21c60 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
21c70 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
21c80 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
21c90 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
21ca0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
21cb0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
21cc0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
21cd0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21ce0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
21cf0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
21d00 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
21d10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
21d20 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
21d30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
21d40 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
21d50 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
21d60 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
21d70 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
21d80 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
21d90 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
21da0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
21db0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
21dc0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
21dd0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
21de0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
21df0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
21e00 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
21e10 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
21e20 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
21e30 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
21e40 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
21e50 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
21e60 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
21e70 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
21e80 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
21e90 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
21ea0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
21eb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
21ec0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
21ed0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
21ee0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
21ef0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
21f00 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
21f10 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
21f20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
21f30 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
21f40 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
21f50 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
21f60 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
21f70 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
21f80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
21f90 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
21fa0 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
21fb0 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
21fc0 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
21fd0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
21fe0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
21ff0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
22000 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
22010 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
22020 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
22030 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
22040 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
22050 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
22060 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
22070 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
22080 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
22090 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
220a0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
220b0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
220c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
220d0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
220e0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
220f0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
22100 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
22110 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
22120 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
22130 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
22140 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
22150 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
22160 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
22170 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
22180 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
22190 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
221a0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
221b0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
221c0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
221d0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
221e0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
221f0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
22200 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
22210 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
22220 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
22230 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
22240 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
22250 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
22260 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
22270 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
22280 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
22290 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
222a0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
222b0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
222c0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
222d0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
222e0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
222f0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
22300 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
22310 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
22320 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
22330 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
22340 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
22350 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
22360 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
22370 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
22380 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
22390 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
223a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
223b0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
223c0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
223d0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
223e0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
223f0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
22400 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
22410 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
22420 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
22430 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
22440 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
22450 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
22460 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
22470 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
22480 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
22490 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
224a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
224b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
224c0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
224d0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
224e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
224f0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
22500 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
22510 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
22520 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
22530 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
22540 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
22550 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
22560 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
22570 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
22580 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
22590 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
225a0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
225b0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
225c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
225d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
225e0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
225f0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
22600 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
22610 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
22620 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
22630 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
22640 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
22650 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
22660 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
22670 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
22680 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
22690 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
226a0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
226b0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
226c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
226d0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
226e0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
226f0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
22700 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
22710 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
22720 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
22730 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
22740 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
22750 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
22760 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
22770 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
22780 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
22790 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
227a0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
227b0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
227c0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
227d0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
227e0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
227f0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
22800 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
22810 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
22820 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
22830 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
22840 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
22850 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
22860 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
22870 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
22880 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
22890 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
228a0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
228b0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
228c0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
228d0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
228e0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
228f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
22900 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
22910 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
22920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22930 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
22940 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
22950 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
22960 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
22970 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
22980 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22990 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
229a0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
229b0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
229c0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
229d0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
229e0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
229f0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
22a00 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
22a10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22a20 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
22a30 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
22a40 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
22a50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
22a60 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
22a70 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
22a80 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
22a90 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
22aa0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
22ab0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
22ac0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
22ad0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
22ae0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
22af0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
22b00 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
22b10 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
22b20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
22b30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
22b40 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
22b50 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
22b60 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
22b70 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
22b80 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
22b90 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
22ba0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
22bb0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
22bc0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
22bd0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
22be0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
22bf0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
22c00 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
22c10 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
22c20 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
22c30 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
22c40 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
22c50 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
22c60 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
22c70 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
22c80 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
22c90 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
22ca0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
22cb0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
22cc0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
22cd0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
22ce0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
22cf0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
22d00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
22d10 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
22d20 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
22d30 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
22d40 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
22d50 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
22d60 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
22d70 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
22d80 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
22d90 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
22da0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
22db0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
22dc0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
22dd0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
22de0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
22df0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
22e00 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
22e10 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
22e20 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
22e30 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
22e40 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
22e50 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
22e60 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
22e70 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
22e80 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
22e90 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
22ea0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
22eb0 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
22ec0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
22ed0 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
22ee0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
22ef0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
22f00 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
22f10 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
22f20 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
22f30 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
22f40 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
22f50 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
22f60 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
22f70 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
22f80 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
22f90 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
22fa0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
22fb0 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
22fc0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
22fd0 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
22fe0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
22ff0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
23000 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
23010 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
23020 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
23030 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
23040 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
23050 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
23060 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
23070 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
23080 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
23090 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
230a0 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
230b0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
230c0 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
230d0 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
230e0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
230f0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
23100 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
23110 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
23120 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
23130 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
23140 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
23150 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
23160 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
23170 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
23180 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
23190 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
231a0 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
231b0 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
231c0 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
231d0 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
231e0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
231f0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
23200 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
23210 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
23220 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
23230 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
23240 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
23250 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
23260 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
23270 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
23280 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
23290 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
232a0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
232b0 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
232c0 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
232d0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
232e0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
232f0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
23300 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
23310 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
23320 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
23330 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
23340 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
23350 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
23360 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
23370 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
23380 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
23390 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
233a0 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
233b0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
233c0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
233d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
233e0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
233f0 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
23400 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
23410 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
23420 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
23430 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
23440 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
23450 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
23460 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
23470 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
23480 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
23490 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
234a0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
234b0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
234c0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
234d0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
234e0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
234f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
23500 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
23510 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
23520 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
23530 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
23540 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
23550 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
23560 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
23570 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
23580 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
23590 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
235a0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
235b0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
235c0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
235d0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
235e0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
235f0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
23600 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
23610 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
23620 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
23630 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
23640 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
23650 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
23660 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
23670 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
23680 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
23690 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
236a0 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
236b0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
236c0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
236d0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
236e0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
236f0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
23700 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
23710 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
23720 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
23730 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
23740 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
23750 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
23760 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
23770 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
23780 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
23790 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
237a0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
237b0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
237c0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
237d0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
237e0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
237f0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
23800 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
23810 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
23820 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
23830 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
23840 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
23850 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
23860 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
23870 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
23880 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
23890 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
238a0 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
238b0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
238c0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
238d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
238e0 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
238f0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
23900 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
23910 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
23920 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
23930 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
23940 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
23950 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
23960 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
23970 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
23980 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
23990 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
239a0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
239b0 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
239c0 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
239d0 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
239e0 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
239f0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
23a00 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
23a10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
23a20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
23a30 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
23a40 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
23a50 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
23a60 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
23a70 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
23a80 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
23a90 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
23aa0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
23ab0 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
23ac0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
23ad0 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
23ae0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
23af0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
23b00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23b10 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
23b20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
23b30 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
23b40 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
23b50 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
23b60 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
23b70 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
23b80 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
23b90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
23ba0 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
23bb0 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
23bc0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
23bd0 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
23be0 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
23bf0 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
23c00 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
23c10 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
23c20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
23c30 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
23c40 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
23c50 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
23c60 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
23c70 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
23c80 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
23c90 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
23ca0 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
23cb0 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
23cc0 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
23cd0 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
23ce0 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
23cf0 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
23d00 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
23d10 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
23d20 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
23d30 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
23d40 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
23d50 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
23d60 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
23d70 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
23d80 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
23d90 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
23da0 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
23db0 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
23dc0 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
23dd0 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
23de0 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
23df0 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
23e00 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
23e10 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
23e20 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
23e30 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
23e40 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
23e50 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
23e60 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
23e70 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
23e80 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
23e90 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
23ea0 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
23eb0 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
23ec0 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
23ed0 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
23ee0 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
23ef0 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
23f00 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
23f10 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
23f20 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
23f30 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
23f40 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
23f50 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
23f60 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
23f70 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
23f80 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
23f90 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
23fa0 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
23fb0 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
23fc0 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
23fd0 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
23fe0 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
23ff0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
24000 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
24010 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
24020 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
24030 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
24040 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
24050 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
24060 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
24070 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
24080 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
24090 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
240a0 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
240b0 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
240c0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
240d0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
240e0 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
240f0 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
24100 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
24110 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
24120 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
24130 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
24140 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
24150 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
24160 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
24170 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
24180 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
24190 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
241a0 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
241b0 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
241c0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
241d0 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
241e0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
241f0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
24200 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
24210 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
24220 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
24230 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
24240 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
24250 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
24260 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
24270 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
24280 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
24290 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
242a0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
242b0 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
242c0 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
242d0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
242e0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
242f0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
24300 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
24310 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
24320 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
24330 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
24340 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
24350 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
24360 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24370 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
24380 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
24390 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
243a0 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
243b0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
243c0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
243d0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
243e0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
243f0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
24400 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
24410 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
24420 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
24430 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
24440 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
24450 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
24460 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
24470 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
24480 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
24490 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
244a0 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
244b0 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
244c0 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
244d0 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
244e0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
244f0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
24500 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
24510 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
24520 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
24530 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
24540 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
24550 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
24560 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
24570 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
24580 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
24590 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
245a0 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
245b0 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
245c0 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
245d0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
245e0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
245f0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
24600 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
24610 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
24620 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
24630 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
24640 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
24650 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
24660 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
24670 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
24680 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
24690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
246a0 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
246b0 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
246c0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
246d0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
246e0 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
246f0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
24700 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
24710 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
24720 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
24730 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
24740 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
24750 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
24760 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
24770 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
24780 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
24790 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
247a0 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
247b0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
247c0 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
247d0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
247e0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
247f0 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
24800 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
24810 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
24820 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
24830 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
24840 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
24850 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
24860 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
24870 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
24880 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
24890 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
248a0 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
248b0 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
248c0 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
248d0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
248e0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
248f0 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
24900 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
24910 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
24920 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
24930 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
24940 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
24950 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
24960 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
24970 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
24980 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
24990 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
249a0 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
249b0 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
249c0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
249d0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
249e0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
249f0 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
24a00 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
24a10 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
24a20 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
24a30 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
24a40 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
24a50 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
24a60 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
24a70 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
24a80 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
24a90 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
24aa0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
24ab0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
24ac0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
24ad0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
24ae0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
24af0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
24b00 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
24b10 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
24b20 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
24b30 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
24b40 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
24b50 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
24b60 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
24b70 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
24b80 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
24b90 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
24ba0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
24bb0 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
24bc0 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
24bd0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
24be0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
24bf0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
24c00 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
24c10 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
24c20 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
24c30 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
24c40 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
24c50 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
24c60 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
24c70 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
24c80 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
24c90 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
24ca0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
24cb0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
24cc0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
24cd0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
24ce0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
24cf0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
24d00 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
24d10 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
24d20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
24d30 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
24d40 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
24d50 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
24d60 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
24d70 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
24d80 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
24d90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
24da0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
24db0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
24dc0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
24dd0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
24de0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
24df0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
24e00 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
24e10 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
24e20 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
24e30 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
24e40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
24e50 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
24e60 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
24e70 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
24e80 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
24e90 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
24ea0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
24eb0 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
24ec0 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
24ed0 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
24ee0 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
24ef0 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
24f00 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
24f10 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
24f20 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
24f30 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
24f40 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
24f50 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
24f60 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
24f70 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
24f80 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
24f90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
24fa0 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
24fb0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
24fc0 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
24fd0 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
24fe0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
24ff0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
25000 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
25010 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
25020 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
25030 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
25040 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
25050 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
25060 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
25070 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
25080 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
25090 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
250a0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
250b0 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
250c0 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
250d0 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
250e0 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
250f0 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
25100 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
25110 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
25120 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
25130 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
25140 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
25150 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
25160 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
25170 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
25180 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
25190 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
251a0 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
251b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
251c0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
251d0 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
251e0 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
251f0 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
25200 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
25210 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
25220 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
25230 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
25240 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
25250 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
25260 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
25270 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
25280 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
25290 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
252a0 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
252b0 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
252c0 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
252d0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
252e0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
252f0 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
25300 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
25310 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
25320 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
25330 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
25340 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
25350 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
25360 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
25370 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
25380 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
25390 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
253a0 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
253b0 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
253c0 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
253d0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
253e0 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
253f0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
25400 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
25410 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
25420 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
25430 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
25440 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
25450 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
25460 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
25470 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
25480 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
25490 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
254a0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
254b0 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
254c0 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
254d0 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
254e0 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
254f0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
25500 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
25510 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
25520 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
25530 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
25540 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
25550 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
25560 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
25570 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
25580 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
25590 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
255a0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
255b0 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
255c0 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
255d0 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
255e0 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
255f0 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
25600 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
25610 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
25620 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
25630 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
25640 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
25650 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
25660 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
25670 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
25680 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
25690 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
256a0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
256b0 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
256c0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
256d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69  .int sqlite3_uri
256e0 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
256f0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
25700 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
25710 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73  int bDefault);.s
25720 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
25730 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
25740 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
25750 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
25760 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
25770 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
25780 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
25790 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ges.** METHOD: s
257a0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66  qlite3.**.** ^If
257b0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
257c0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
257d0 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
257e0 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ith .** [databas
257f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
25800 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  failed, then the
25810 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
25820 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  (D) interface.**
25830 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
25840 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
25850 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
25860 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
25870 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c   that.** API cal
25880 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73  l..** If the mos
25890 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
258a0 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c  l was successful
258b0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
258c0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
258d0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
258e0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  ) is undefined..
258f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25900 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
25910 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
25920 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
25930 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
25940 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
25950 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
25960 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
25970 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
25980 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
25990 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
259a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
259b0 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
259c0 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
259d0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
259e0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
259f0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
25a00 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
25a10 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
25a20 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
25a30 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
25a40 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
25a50 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
25a60 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
25a70 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
25a80 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
25a90 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
25aa0 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
25ab0 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
25ac0 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
25ad0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
25ae0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
25af0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
25b00 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
25b10 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
25b20 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
25b30 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
25b40 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
25b50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
25b60 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
25b70 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
25b80 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
25b90 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
25ba0 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
25bb0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
25bc0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
25bd0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
25be0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
25bf0 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
25c00 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
25c10 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
25c20 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
25c30 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
25c40 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
25c50 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
25c60 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
25c70 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
25c80 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
25c90 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
25ca0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
25cb0 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
25cc0 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
25cd0 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
25ce0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
25cf0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
25d00 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
25d10 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
25d20 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
25d30 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
25d40 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
25d50 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
25d60 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
25d70 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
25d80 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
25d90 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
25da0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25db0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
25dc0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
25dd0 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
25de0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
25df0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
25e00 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
25e10 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
25e20 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
25e30 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
25e40 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
25e50 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
25e60 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
25e70 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
25e80 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
25e90 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
25ea0 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
25eb0 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
25ec0 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
25ed0 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
25ee0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
25ef0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
25f00 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
25f10 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
25f20 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
25f30 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
25f40 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
25f50 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
25f60 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
25f70 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
25f80 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
25f90 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
25fa0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
25fb0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
25fc0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
25fd0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
25fe0 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  3*);.const char 
25ff0 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
26000 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
26010 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20  I3REF: Prepared 
26020 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
26030 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
26040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26050 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
26060 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
26070 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
26080 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
26090 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
260a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
260b0 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  .** has been com
260c0 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72  piled into binar
260d0 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65  y form and is re
260e0 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61  ady to be evalua
260f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b  ted..**.** Think
26100 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61   of each SQL sta
26110 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61  tement as a sepa
26120 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72  rate computer pr
26130 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f  ogram.  The.** o
26140 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
26150 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e   is source code.
26160 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61    A prepared sta
26170 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a  tement object .*
26180 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65  * is the compile
26190 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20  d object code.  
261a0 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20  All SQL must be 
261b0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
261c0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
261d0 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74  tement before it
261e0 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a   can be run..**.
261f0 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c  ** The life-cycl
26200 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20  e of a prepared 
26210 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
26220 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69   usually goes li
26230 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
26240 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
26250 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20  te the prepared 
26260 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
26270 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
26280 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a  prepare_v2()]..*
26290 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
262a0 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  es to [parameter
262b0 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
262c0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
262d0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
262e0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
262f0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
26300 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
26310 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
26320 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
26330 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
26340 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
26350 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26360 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
26370 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
26380 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
26390 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
263a0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
263b0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
263c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
263d0 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
263e0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
263f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
26400 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
26410 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
26420 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20  -time Limits.** 
26430 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
26440 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
26450 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
26460 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
26470 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
26480 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
26490 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
264a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
264b0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
264c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
264d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
264e0 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
264f0 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
26500 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
26510 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
26520 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
26530 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
26540 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
26550 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
26560 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
26570 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
26580 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
26590 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
265a0 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
265b0 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
265c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
265d0 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
265e0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
265f0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
26600 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
26610 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
26620 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
26630 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
26640 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
26650 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
26660 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
26670 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
26680 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
26690 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
266a0 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
266b0 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
266c0 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
266d0 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
266e0 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
266f0 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
26700 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
26710 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
26720 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
26730 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
26740 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
26750 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
26760 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
26770 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
26780 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
26790 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
267a0 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
267b0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
267c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
267d0 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
267e0 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
267f0 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
26800 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
26810 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
26820 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
26830 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
26840 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
26850 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
26860 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
26870 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
26880 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
26890 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
268a0 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
268b0 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
268c0 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
268d0 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
268e0 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
268f0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
26900 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
26910 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
26920 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
26930 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
26940 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
26950 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
26960 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
26970 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
26980 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
26990 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
269a0 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
269b0 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
269c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
269d0 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
269e0 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
269f0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
26a00 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
26a10 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
26a20 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
26a30 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
26a40 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
26a50 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
26a60 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
26a70 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
26a80 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
26a90 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
26aa0 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
26ab0 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
26ac0 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
26ad0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
26ae0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
26af0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
26b00 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
26b10 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
26b20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
26b30 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
26b40 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
26b50 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
26b60 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
26b70 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
26b80 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
26b90 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
26ba0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
26bb0 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
26bc0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
26bd0 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
26be0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
26bf0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
26c00 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
26c10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
26c20 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
26c30 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
26c40 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
26c50 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
26c60 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
26c70 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
26c80 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
26c90 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
26ca0 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
26cb0 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
26cc0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
26cd0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
26ce0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
26cf0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
26d00 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
26d10 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
26d20 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
26d30 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
26d40 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
26d50 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
26d60 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
26d70 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
26d80 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
26d90 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26da0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
26db0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26dc0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
26dd0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
26de0 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
26df0 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
26e00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26e10 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
26e20 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26e30 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
26e40 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26e50 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
26e60 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
26e70 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
26e80 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26e90 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
26ea0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26eb0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
26ec0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26ed0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
26ee0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
26ef0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
26f00 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
26f10 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
26f20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
26f30 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
26f40 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
26f50 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
26f60 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
26f70 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
26f80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26f90 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
26fa0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26fb0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
26fc0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26fd0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
26fe0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
26ff0 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
27000 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
27010 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
27020 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
27030 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
27040 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
27050 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27060 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
27070 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
27080 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
27090 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
270a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
270b0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
270c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
270d0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
270e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
270f0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
27100 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
27110 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
27120 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
27130 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
27140 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
27150 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
27160 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
27170 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
27180 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
27190 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
271a0 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
271b0 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
271c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
271d0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
271e0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
271f0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
27200 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
27210 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
27220 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
27230 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
27240 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
27250 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
27260 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
27270 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
27280 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27290 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
272a0 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
272b0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
272c0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
272d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
272e0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
272f0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
27300 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
27310 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
27320 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
27330 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
27340 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
27350 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
27360 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
27370 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
27380 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27390 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
273a0 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
273b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
273c0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
273d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
273e0 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
273f0 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
27400 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
27410 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
27420 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27430 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
27440 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27450 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
27460 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
27470 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
27480 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
27490 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
274a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
274b0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
274c0 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
274d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
274e0 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
274f0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
27500 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
27510 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
27520 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
27530 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
27540 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
27550 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
27560 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
27570 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
27580 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
27590 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
275a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
275b0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
275c0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
275d0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
275e0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
275f0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
27600 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27610 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
27620 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
27630 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27640 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
27650 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
27660 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27670 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
27680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
27690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
276a0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
276b0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
276c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
276d0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
276e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
276f0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
27700 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
27710 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
27720 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
27730 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
27740 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
27750 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
27760 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
27770 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
27780 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
27790 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
277a0 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
277b0 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
277c0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
277d0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
277e0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
277f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
27800 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
27810 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
27820 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
27830 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
27840 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
27850 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
27860 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
27870 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
27880 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
27890 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
278a0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
278b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
278c0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
278d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
278e0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
278f0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
27900 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
27910 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
27920 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
27930 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
27940 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
27950 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
27960 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
27970 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
27980 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
27990 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
279a0 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
279b0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
279c0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
279d0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
279e0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
279f0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
27a00 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
27a10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
27a20 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
27a30 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
27a40 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
27a50 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
27a60 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
27a70 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
27a80 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
27a90 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69  gument is negati
27aa0 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ve, then zSql is
27ab0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
27ac0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
27ad0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
27ae0 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c  yte is positive,
27af0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a   then it is the.
27b00 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
27b10 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
27b20 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73  l.  ^If nByte is
27b30 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70   zero, then no p
27b40 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
27b50 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65  ment is generate
27b60 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
27b70 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74  ler knows that t
27b80 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
27b90 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
27ba0 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  ated, then.** th
27bb0 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70  ere is a small p
27bc0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
27bd0 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20  tage to passing 
27be0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
27bf0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68  er that.** is th
27c00 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
27c10 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
27c20 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
27c30 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
27c40 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  l-terminator..**
27c50 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
27c60 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
27c70 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
27c80 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
27c90 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
27ca0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
27cb0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
27cc0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
27cd0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
27ce0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
27cf0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
27d00 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
27d10 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
27d20 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
27d30 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
27d40 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
27d50 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
27d60 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
27d70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
27d80 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
27d90 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
27da0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
27db0 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
27dc0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
27dd0 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
27de0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
27df0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
27e00 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
27e10 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
27e20 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
27e30 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
27e40 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
27e50 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
27e60 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
27e70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
27e80 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
27e90 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
27ea0 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
27eb0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
27ec0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
27ed0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
27ee0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
27ef0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
27f00 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
27f10 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
27f20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
27f30 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
27f40 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
27f50 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
27f60 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
27f70 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
27f80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
27f90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27fa0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
27fb0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
27fc0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
27fd0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
27fe0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
27ff0 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
28000 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
28010 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
28020 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
28030 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
28040 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
28050 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
28060 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
28070 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
28080 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
28090 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
280a0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
280b0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
280c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
280d0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
280e0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
280f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
28100 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
28110 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
28120 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
28130 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
28140 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
28150 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
28160 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
28170 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
28180 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
28190 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
281a0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
281b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
281c0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
281d0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
281e0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
281f0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
28200 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
28210 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
28220 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
28230 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
28240 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
28250 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
28260 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
28270 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
28280 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
28290 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
282a0 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
282b0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
282c0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
282d0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
282e0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
282f0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
28300 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
28310 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
28320 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
28330 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
28340 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
28350 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
28360 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
28370 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
28380 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
28390 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
283a0 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
283b0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
283c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
283d0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
283e0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
283f0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
28400 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
28410 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
28420 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
28430 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
28440 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
28450 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
28460 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
28470 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
28480 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
28490 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
284a0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
284b0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
284c0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
284d0 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
284e0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
284f0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
28500 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
28510 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
28520 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
28530 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
28540 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
28550 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
28560 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
28570 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
28580 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
28590 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
285a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
285b0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
285c0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
285d0 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
285e0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
285f0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
28600 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
28610 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
28620 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
28630 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
28640 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
28650 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
28660 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
28670 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
28680 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
28690 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
286a0 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
286b0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
286c0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
286d0 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
286e0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
286f0 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
28700 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
28710 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
28720 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
28730 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
28740 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
28750 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
28760 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
28770 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
28780 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
28790 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
287a0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
287b0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
287c0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
287d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
287e0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
287f0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
28800 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
28810 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
28820 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
28830 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
28840 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
28850 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
28860 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
28870 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
28880 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
28890 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
288a0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
288b0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
288c0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
288d0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
288e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
288f0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
28900 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
28910 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
28920 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
28930 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
28940 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
28950 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
28960 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
28970 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
28980 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
28990 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
289a0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
289b0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
289c0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
289d0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
289e0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
289f0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
28a00 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
28a10 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
28a20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
28a30 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
28a40 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
28a50 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
28a60 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
28a70 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
28a80 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
28a90 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
28aa0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
28ab0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
28ac0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
28ad0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
28ae0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28af0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
28b00 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
28b10 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
28b20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
28b30 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
28b40 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
28b50 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
28b60 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
28b70 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
28b80 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
28b90 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
28ba0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
28bb0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
28bc0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
28bd0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28be0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
28bf0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
28c00 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
28c10 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
28c20 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
28c30 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
28c40 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
28c50 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
28c60 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
28c70 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
28c80 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
28c90 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
28ca0 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
28cb0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
28cc0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
28cd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28ce0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
28cf0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
28d00 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
28d10 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
28d20 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
28d30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28d40 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
28d50 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
28d60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
28d70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
28d80 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
28d90 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
28da0 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
28db0 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54   Database.** MET
28dc0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
28dd0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
28de0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
28df0 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
28e00 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
28e10 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
28e20 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
28e30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28e40 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
28e50 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
28e60 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
28e70 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
28e80 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
28e90 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
28ea0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
28eb0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
28ec0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
28ed0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
28ee0 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
28ef0 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
28f00 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
28f10 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
28f20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
28f30 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
28f40 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
28f50 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
28f60 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
28f70 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
28f80 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
28f90 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
28fa0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
28fb0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
28fc0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
28fd0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
28fe0 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
28ff0 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
29000 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
29010 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
29020 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
29030 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
29040 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
29050 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
29060 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
29070 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
29080 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
29090 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
290a0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
290b0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
290c0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
290d0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
290e0 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
290f0 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
29100 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
29110 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
29120 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
29130 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
29140 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
29150 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
29160 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
29170 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
29180 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
29190 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
291a0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
291b0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
291c0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
291d0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
291e0 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
291f0 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
29200 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
29210 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
29220 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
29230 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
29240 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
29250 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
29260 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
29270 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
29280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29290 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
292a0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
292b0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
292c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
292d0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
292e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
292f0 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
29300 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
29310 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29320 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
29330 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
29340 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
29350 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
29360 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
29370 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
29380 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
29390 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
293a0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
293b0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
293c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
293d0 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
293e0 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
293f0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
29400 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
29410 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63  neither run to c
29420 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72  ompletion (retur
29430 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ned.** [SQLITE_D
29440 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ONE] from [sqlit
29450 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72  e3_step(S)]) nor
29460 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
29470 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
29480 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
29490 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
294a0 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
294b0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
294c0 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
294d0 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
294e0 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
294f0 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
29500 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
29510 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
29520 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
29530 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
29540 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
29550 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
29560 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
29570 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
29580 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
29590 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
295a0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
295b0 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
295c0 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
295d0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
295e0 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
295f0 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
29600 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
29610 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
29620 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
29630 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
29640 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
29650 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
29660 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
29670 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
29680 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
29690 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
296a0 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e  tion open..*/.in
296b0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  t sqlite3_stmt_b
296c0 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
296d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
296e0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
296f0 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
29700 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
29710 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
29720 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
29730 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29740 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
29750 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
29760 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29770 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
29780 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
29790 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
297a0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
297b0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
297c0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
297d0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
297e0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
297f0 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
29800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29810 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
29820 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
29830 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
29840 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
29850 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
29860 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
29870 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
29880 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
29890 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
298a0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
298b0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
298c0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
298d0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
298e0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
298f0 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
29900 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
29910 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
29920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
29930 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
29940 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
29950 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
29960 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
29970 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
29980 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
29990 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
299a0 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a  e3_value.  The.*
299b0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
299c0 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63  _dup()] interfac
299d0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
299e0 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77   construct a new
299f0 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73   .** protected s
29a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f  qlite3_value fro
29a10 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  m an unprotected
29a20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
29a30 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
29a40 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
29a50 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
29a60 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
29a70 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
29a80 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
29a90 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
29aa0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
29ab0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
29ac0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
29ad0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
29ae0 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
29af0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
29b00 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
29b10 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
29b20 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
29b30 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
29b40 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
29b50 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
29b60 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
29b70 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
29b80 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
29b90 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
29ba0 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
29bb0 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
29bc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
29bd0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
29be0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
29bf0 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
29c00 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
29c10 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
29c20 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
29c30 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
29c40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29c50 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
29c60 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
29c70 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
29c80 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
29c90 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
29ca0 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
29cb0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
29cc0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
29cd0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
29ce0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
29cf0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
29d00 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
29d10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29d20 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
29d30 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
29d40 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
29d50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29d60 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
29d70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
29d80 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
29d90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
29da0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
29db0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
29dc0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
29dd0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
29de0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29df0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
29e00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29e10 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
29e20 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
29e30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29e40 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
29e50 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
29e60 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
29e70 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
29e80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
29e90 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
29ea0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
29eb0 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
29ec0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
29ed0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
29ee0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
29ef0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29f00 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
29f10 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
29f20 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
29f30 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
29f40 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
29f50 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
29f60 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
29f70 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
29f80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
29f90 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
29fa0 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
29fb0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
29fc0 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
29fd0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
29fe0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
29ff0 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
2a000 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
2a010 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a020 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
2a030 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2a040 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2a050 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2a060 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
2a070 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
2a080 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
2a090 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2a0a0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
2a0b0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
2a0c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
2a0d0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
2a0e0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
2a0f0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
2a100 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2a110 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
2a120 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2a130 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
2a140 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2a150 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
2a160 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2a170 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
2a180 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
2a190 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
2a1a0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
2a1b0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
2a1c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
2a1d0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
2a1e0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
2a1f0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2a200 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
2a210 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
2a220 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
2a230 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
2a240 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48  binding}.** METH
2a250 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2a260 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
2a270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
2a280 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
2a290 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a2a0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
2a2b0 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
2a2c0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
2a2d0 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
2a2e0 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
2a2f0 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
2a300 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
2a310 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2a320 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
2a330 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
2a340 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
2a350 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
2a360 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
2a370 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
2a380 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
2a390 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
2a3a0 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
2a3b0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
2a3c0 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
2a3d0 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
2a3e0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
2a3f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
2a400 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
2a410 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
2a420 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
2a430 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
2a440 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
2a450 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2a460 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
2a470 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
2a480 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2a490 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2a4a0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2a4b0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
2a4c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2a4d0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2a4e0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
2a4f0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
2a500 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2a510 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
2a520 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2a530 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2a540 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
2a550 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
2a560 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
2a570 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
2a580 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2a590 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
2a5a0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
2a5b0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
2a5c0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
2a5d0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
2a5e0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
2a5f0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
2a600 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
2a610 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
2a620 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
2a630 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
2a640 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
2a650 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
2a660 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
2a670 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a680 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
2a690 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
2a6a0 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
2a6b0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
2a6c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2a6d0 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
2a6e0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
2a6f0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
2a700 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
2a710 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
2a720 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
2a730 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
2a740 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
2a750 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
2a760 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2a770 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
2a780 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
2a790 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
2a7a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2a7b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2a7c0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2a7d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2a7e0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2a7f0 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
2a800 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
2a810 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
2a820 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
2a830 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
2a840 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
2a850 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
2a860 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
2a870 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
2a880 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
2a890 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
2a8a0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
2a8b0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2a8c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
2a8d0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
2a8e0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
2a8f0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
2a900 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
2a910 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
2a920 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2a930 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
2a940 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
2a950 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2a960 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a970 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2a980 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2a990 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2a9a0 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
2a9b0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
2a9c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2a9d0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
2a9e0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
2a9f0 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
2aa00 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2aa10 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2aa20 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
2aa30 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
2aa40 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2aa50 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
2aa60 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
2aa70 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
2aa80 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
2aa90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2aaa0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2aab0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20  ind_text16() or 
2aac0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2aad0 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68  t64() then.** th
2aae0 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
2aaf0 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
2ab00 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
2ab10 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
2ab20 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
2ab30 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
2ab40 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
2ab50 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
2ab60 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
2ab70 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
2ab80 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
2ab90 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
2aba0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2abb0 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
2abc0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
2abd0 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
2abe0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
2abf0 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
2ac00 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
2ac10 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
2ac20 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
2ac30 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
2ac40 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2ac50 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2ac60 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20  to the BLOB and 
2ac70 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69  string binding i
2ac80 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2ac90 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
2aca0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
2acb0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
2acc0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
2acd0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
2ace0 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
2acf0 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
2ad00 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
2ad10 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2ad20 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
2ad30 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64  the call to bind
2ad40 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e   API fails..** ^
2ad50 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
2ad60 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
2ad70 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
2ad80 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
2ad90 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
2ada0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
2adb0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
2adc0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
2add0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
2ade0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2adf0 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
2ae00 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2ae10 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
2ae20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
2ae30 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
2ae40 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
2ae50 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
2ae60 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
2ae70 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
2ae80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2ae90 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
2aea0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
2aeb0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2aec0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2aed0 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62  _text64() must b
2aee0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c  e one of.** [SQL
2aef0 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
2af00 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
2af10 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
2af20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2af30 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74  .** to specify t
2af40 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  he encoding of t
2af50 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74  he text in the t
2af60 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
2af70 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68   If.** the sixth
2af80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2af90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2afa0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
2afb0 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20   the.** allowed 
2afc0 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f  values shown abo
2afd0 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65  ve, or if the te
2afe0 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  xt encoding is d
2aff0 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d  ifferent.** from
2b000 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
2b010 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ecified by the s
2b020 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  ixth parameter, 
2b030 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2b040 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  r.** is undefine
2b050 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2b060 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2b070 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
2b080 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
2b090 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
2b0a0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
2b0b0 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
2b0c0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
2b0d0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
2b0e0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
2b0f0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
2b100 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
2b110 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
2b120 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
2b130 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
2b140 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
2b150 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
2b160 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
2b170 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
2b180 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
2b190 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
2b1a0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
2b1b0 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
2b1c0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
2b1d0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
2b1e0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
2b1f0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
2b200 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
2b210 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
2b220 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2b230 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2b240 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
2b250 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
2b260 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b270 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
2b280 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b290 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
2b2a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2b2b0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
2b2c0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
2b2d0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2b2e0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
2b2f0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
2b300 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2b310 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
2b320 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
2b330 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
2b340 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b350 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
2b360 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
2b370 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
2b380 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2b390 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
2b3a0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
2b3b0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
2b3c0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
2b3d0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
2b3e0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
2b3f0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
2b400 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
2b410 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
2b420 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
2b430 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2b440 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
2b450 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
2b460 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
2b470 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
2b480 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f  ..** ^[SQLITE_TO
2b490 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72  OBIG] might be r
2b4a0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73  eturned if the s
2b4b0 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20  ize of a string 
2b4c0 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65  or BLOB.** excee
2b4d0 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65  ds limits impose
2b4e0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  d by [sqlite3_li
2b4f0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2b500 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a  IT_LENGTH]) or.*
2b510 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  * [SQLITE_MAX_LE
2b520 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  NGTH]..** ^[SQLI
2b530 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
2b540 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
2b550 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
2b560 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
2b570 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
2b580 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2b590 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
2b5a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2b5b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2b5c0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2b5d0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2b5e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2b5f0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
2b600 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b610 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2b620 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b630 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2b640 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2b650 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
2b660 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2b670 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b680 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
2b690 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2b6a0 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f   void*, sqlite3_
2b6b0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2b6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b6d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b6e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2b6f0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
2b700 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
2b710 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
2b720 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
2b730 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2b740 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2b750 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
2b760 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b770 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2b780 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b790 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
2b7a0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
2b7b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2b7c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b7d0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69  nt,const char*,i
2b7e0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2b7f0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2b800 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
2b810 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b820 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2b830 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2b840 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b850 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ind_text64(sqlit
2b860 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2b870 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
2b880 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
2b890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b8a0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2b8b0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68  d*), unsigned ch
2b8c0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e  ar encoding);.in
2b8d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
2b8e0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2b8f0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
2b900 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2b910 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b920 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2b930 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2b940 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t n);.int sqlite
2b950 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36  3_bind_zeroblob6
2b960 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2b970 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69   int, sqlite3_ui
2b980 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
2b990 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2b9a0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2b9b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2b9c0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2b9d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2b9e0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2b9f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2ba00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2ba10 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2ba20 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2ba30 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2ba40 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2ba50 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2ba60 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2ba70 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2ba80 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2ba90 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2baa0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2bab0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2bac0 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2bad0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2bae0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2baf0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2bb00 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2bb10 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2bb20 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2bb30 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2bb40 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2bb50 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2bb60 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2bb70 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2bb80 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2bb90 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2bba0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2bbb0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2bbc0 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2bbd0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2bbe0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2bbf0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2bc00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2bc10 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2bc20 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2bc30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2bc40 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2bc50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2bc60 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2bc70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2bc80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2bc90 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2bca0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2bcb0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2bcc0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2bcd0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2bce0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2bcf0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2bd00 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2bd10 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2bd20 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2bd30 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2bd40 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2bd50 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2bd60 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2bd70 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2bd80 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2bd90 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2bda0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2bdb0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2bdc0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2bdd0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2bde0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2bdf0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2be00 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2be10 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2be20 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2be30 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2be40 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2be50 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2be60 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2be70 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2be80 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2be90 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2bea0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2beb0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2bec0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2bed0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2bee0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2bef0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2bf00 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2bf10 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2bf20 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2bf30 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2bf40 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2bf50 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2bf60 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2bf70 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2bf80 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2bf90 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2bfa0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2bfb0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2bfc0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2bfd0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2bfe0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2bff0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2c000 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2c010 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2c020 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2c030 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2c040 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2c050 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2c060 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2c070 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2c080 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c090 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2c0a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2c0b0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2c0c0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2c0d0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
2c0e0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
2c0f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c100 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c110 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
2c120 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
2c130 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45  Given Name.** ME
2c140 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c150 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
2c160 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
2c170 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
2c180 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
2c190 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
2c1a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
2c1b0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
2c1c0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
2c1d0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
2c1e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2c1f0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2c200 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
2c210 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
2c220 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
2c230 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
2c240 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
2c250 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
2c260 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
2c270 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
2c280 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
2c290 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
2c2a0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
2c2b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2c2c0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2c2d0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2c2e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2c2f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2c300 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2c310 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2c320 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2c330 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c340 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f  eter_name()]..*/
2c350 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2c360 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2c370 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
2c380 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2c390 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
2c3a0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
2c3b0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
2c3c0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2c3d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c3e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c3f0 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
2c400 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
2c410 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
2c420 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
2c430 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
2c440 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2c450 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
2c460 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c470 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
2c480 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
2c490 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
2c4a0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
2c4b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2c4c0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
2c4d0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2c4e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2c4f0 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
2c500 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2c510 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c520 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c530 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2c540 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2c550 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2c560 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2c570 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2c580 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
2c590 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2c5a0 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
2c5b0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2c5c0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
2c5d0 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
2c5e0 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
2c5f0 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
2c600 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2c610 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
2c620 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2c630 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
2c640 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2c650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2c660 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
2c670 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
2c680 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2c690 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
2c6a0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c6b0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
2c6c0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
2c6d0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
2c6e0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2c6f0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
2c700 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
2c710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2c720 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
2c730 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2c740 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2c750 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
2c760 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
2c770 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2c780 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
2c790 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2c7a0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
2c7b0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2c7c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2c7d0 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
2c7e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2c7f0 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
2c800 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
2c810 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
2c820 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2c830 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
2c840 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
2c850 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
2c860 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
2c870 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2c880 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
2c890 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
2c8a0 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
2c8b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2c8c0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
2c8d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2c8e0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2c8f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2c900 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2c910 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2c920 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2c930 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c940 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2c950 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2c960 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
2c970 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2c980 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
2c990 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c9a0 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
2c9b0 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
2c9c0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
2c9d0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
2c9e0 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
2c9f0 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
2ca00 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
2ca10 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
2ca20 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
2ca30 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
2ca40 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
2ca50 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2ca60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
2ca70 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
2ca80 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
2ca90 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
2caa0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
2cab0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
2cac0 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
2cad0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
2cae0 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
2caf0 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
2cb00 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
2cb10 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2cb20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
2cb30 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
2cb40 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
2cb50 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
2cb60 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2cb70 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
2cb80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2cb90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2cba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2cbb0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2cbc0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
2cbd0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
2cbe0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
2cbf0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
2cc00 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2cc10 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2cc20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
2cc30 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
2cc40 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
2cc50 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
2cc60 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
2cc70 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
2cc80 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
2cc90 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
2cca0 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
2ccb0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
2ccc0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
2ccd0 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
2cce0 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
2ccf0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
2cd00 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
2cd10 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
2cd20 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
2cd30 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2cd40 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
2cd50 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
2cd60 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
2cd70 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
2cd80 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
2cd90 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
2cda0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
2cdb0 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
2cdc0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2cdd0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
2cde0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2cdf0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
2ce00 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
2ce10 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ce20 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2ce30 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2ce40 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2ce50 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2ce60 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2ce70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2ce80 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2ce90 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2cea0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
2ceb0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2cec0 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
2ced0 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
2cee0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
2cef0 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
2cf00 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
2cf10 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
2cf20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
2cf30 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
2cf40 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
2cf50 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2cf60 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
2cf70 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
2cf80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2cf90 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2cfa0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
2cfb0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
2cfc0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
2cfd0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
2cfe0 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
2cff0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
2d000 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
2d010 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
2d020 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
2d030 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
2d040 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
2d050 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
2d060 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
2d070 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
2d080 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
2d090 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
2d0a0 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
2d0b0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
2d0c0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
2d0d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2d0e0 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
2d0f0 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
2d100 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
2d110 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
2d120 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2d130 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
2d140 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
2d150 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
2d160 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
2d170 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
2d180 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
2d190 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
2d1a0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
2d1b0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
2d1c0 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
2d1d0 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
2d1e0 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
2d1f0 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
2d200 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
2d210 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
2d220 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
2d230 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
2d240 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
2d250 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
2d260 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
2d270 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
2d280 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
2d290 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
2d2a0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
2d2b0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
2d2c0 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
2d2d0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2d2e0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2d2f0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
2d300 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
2d310 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
2d320 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d330 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
2d340 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2d350 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2d360 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
2d370 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2d380 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2d390 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
2d3a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d3b0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
2d3c0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
2d3d0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
2d3e0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
2d3f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d400 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
2d410 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
2d420 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2d430 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2d440 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
2d450 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2d460 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2d470 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2d480 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2d490 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2d4a0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2d4b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2d4c0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
2d4d0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2d4e0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
2d4f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2d500 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2d510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2d520 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2d530 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2d540 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2d550 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2d560 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2d570 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2d580 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2d590 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
2d5a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2d5b0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2d5c0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
2d5d0 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
2d5e0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
2d5f0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2d600 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
2d610 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2d620 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d630 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
2d640 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
2d650 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2d660 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
2d670 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
2d680 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
2d690 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
2d6a0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
2d6b0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
2d6c0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2d6d0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
2d6e0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
2d6f0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
2d700 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
2d710 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
2d720 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2d730 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2d740 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
2d750 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
2d760 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
2d770 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2d780 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2d790 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
2d7a0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
2d7b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2d7c0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
2d7d0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2d7e0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
2d7f0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
2d800 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
2d810 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
2d820 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2d830 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
2d840 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
2d850 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
2d860 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
2d870 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
2d880 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
2d890 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
2d8a0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
2d8b0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
2d8c0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
2d8d0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
2d8e0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
2d8f0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
2d900 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
2d910 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
2d920 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
2d930 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
2d940 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
2d950 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
2d960 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
2d970 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
2d980 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
2d990 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
2d9a0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
2d9b0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
2d9c0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
2d9d0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
2d9e0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
2d9f0 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
2da00 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2da10 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
2da20 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
2da30 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
2da40 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
2da50 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
2da60 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2da70 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2da80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2da90 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2daa0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2dab0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
2dac0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2dad0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2dae0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
2daf0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
2db00 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2db10 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
2db20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2db30 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
2db40 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
2db50 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2db60 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2db70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2db80 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
2db90 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
2dba0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
2dbb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2dbc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2dbd0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
2dbe0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
2dbf0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
2dc00 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
2dc10 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
2dc20 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
2dc30 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
2dc40 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
2dc50 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2dc60 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
2dc70 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
2dc80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
2dc90 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2dca0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
2dcb0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
2dcc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2dcd0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2dce0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2dcf0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
2dd00 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2dd10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dd20 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2dd30 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
2dd40 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
2dd50 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
2dd60 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2dd70 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
2dd80 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
2dd90 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2dda0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
2ddb0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
2ddc0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
2ddd0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2dde0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
2ddf0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
2de00 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
2de10 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
2de20 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
2de30 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
2de40 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
2de50 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
2de60 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2de70 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
2de80 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
2de90 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
2dea0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
2deb0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
2dec0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
2ded0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
2dee0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
2def0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2df00 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
2df10 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
2df20 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
2df30 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
2df40 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
2df50 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
2df60 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
2df70 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
2df80 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
2df90 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
2dfa0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
2dfb0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
2dfc0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2dfd0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
2dfe0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
2dff0 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
2e000 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
2e010 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
2e020 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
2e030 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
2e040 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
2e050 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
2e060 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2e070 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
2e080 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
2e090 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
2e0a0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
2e0b0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2e0c0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2e0d0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
2e0e0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
2e0f0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
2e100 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e110 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
2e120 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2e130 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2e140 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
2e150 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
2e160 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
2e170 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
2e180 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
2e190 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
2e1a0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
2e1b0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
2e1c0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
2e1d0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
2e1e0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
2e1f0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
2e200 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
2e210 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
2e220 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
2e230 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2e240 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
2e250 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
2e260 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
2e270 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
2e280 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
2e290 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
2e2a0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
2e2b0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
2e2c0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
2e2d0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
2e2e0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2e2f0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2e300 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
2e310 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
2e320 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
2e330 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2e340 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
2e350 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
2e360 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
2e370 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2e380 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
2e390 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
2e3a0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
2e3b0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
2e3c0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
2e3d0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
2e3e0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
2e3f0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2e400 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
2e410 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2e420 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
2e430 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
2e440 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
2e450 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2e460 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
2e470 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
2e480 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
2e490 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
2e4a0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
2e4b0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
2e4c0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
2e4d0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
2e4e0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
2e4f0 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
2e500 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e510 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
2e520 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
2e530 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2e540 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
2e550 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
2e560 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
2e570 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2e580 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2e590 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
2e5a0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
2e5b0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
2e5c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e5d0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
2e5e0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
2e5f0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
2e600 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
2e610 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
2e620 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
2e630 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
2e640 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
2e650 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
2e660 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e670 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
2e680 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
2e690 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
2e6a0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
2e6b0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2e6c0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
2e6d0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2e6e0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
2e6f0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
2e700 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
2e710 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e720 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
2e730 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
2e740 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
2e750 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2e760 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
2e770 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2e780 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
2e790 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
2e7a0 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
2e7b0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
2e7c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
2e7d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
2e7e0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
2e7f0 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
2e800 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2e810 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
2e820 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
2e830 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
2e840 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
2e850 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
2e860 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
2e870 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
2e880 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
2e890 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
2e8a0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
2e8b0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
2e8c0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
2e8d0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
2e8e0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
2e8f0 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
2e900 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2e910 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
2e920 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
2e930 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2e940 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
2e950 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
2e960 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
2e970 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
2e980 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
2e990 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
2e9a0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
2e9b0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2e9c0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
2e9d0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
2e9e0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
2e9f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2ea00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2ea10 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
2ea20 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
2ea30 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
2ea40 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
2ea50 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
2ea60 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
2ea70 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
2ea80 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
2ea90 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
2eaa0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
2eab0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
2eac0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
2ead0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
2eae0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
2eaf0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
2eb00 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
2eb10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2eb20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2eb30 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
2eb40 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
2eb50 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
2eb60 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2eb70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2eb80 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
2eb90 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
2eba0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
2ebb0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
2ebc0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
2ebd0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
2ebe0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
2ebf0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2ec00 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2ec10 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2ec20 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
2ec30 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2ec40 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2ec50 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2ec60 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45  result set.** ME
2ec70 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2ec80 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2ec90 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2eca0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2ecb0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2ecc0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2ecd0 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
2ece0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2ecf0 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
2ed00 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2ed10 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
2ed20 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
2ed30 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
2ed40 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
2ed50 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
2ed60 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
2ed70 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
2ed80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
2ed90 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
2eda0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
2edb0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
2edc0 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
2edd0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2ede0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
2edf0 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
2ee00 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
2ee10 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
2ee20 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2ee30 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
2ee40 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
2ee50 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
2ee60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2ee70 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
2ee80 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
2ee90 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2eea0 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
2eeb0 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
2eec0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2eed0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
2eee0 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
2eef0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
2ef00 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
2ef10 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
2ef20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
2ef30 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
2ef40 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
2ef50 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
2ef60 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
2ef70 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
2ef80 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
2ef90 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
2efa0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2efb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2efc0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
2efd0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
2efe0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2eff0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2f000 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
2f010 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
2f020 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
2f030 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
2f040 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
2f050 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
2f060 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
2f070 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
2f080 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
2f090 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2f0a0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
2f0b0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
2f0c0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
2f0d0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
2f0e0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
2f0f0 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
2f100 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2f110 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
2f120 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
2f130 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
2f140 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
2f150 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
2f160 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
2f170 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
2f180 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
2f190 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
2f1a0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
2f1b0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
2f1c0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
2f1d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2f1e0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
2f1f0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
2f200 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
2f210 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
2f220 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
2f230 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
2f240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f250 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
2f260 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
2f270 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2f280 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
2f290 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
2f2a0 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
2f2b0 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
2f2c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
2f2d0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
2f2e0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
2f2f0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
2f300 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2f310 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
2f320 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
2f330 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
2f340 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
2f350 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f360 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
2f370 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2f380 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2f390 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
2f3a0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
2f3b0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
2f3c0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
2f3d0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
2f3e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
2f3f0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2f400 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
2f410 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2f420 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
2f430 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2f440 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
2f450 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
2f460 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
2f470 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
2f480 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
2f490 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
2f4a0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2f4b0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2f4c0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
2f4d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
2f4e0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
2f4f0 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
2f500 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
2f510 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
2f520 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
2f530 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
2f540 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2f550 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
2f560 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
2f570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2f580 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
2f590 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2f5a0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
2f5b0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
2f5c0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
2f5d0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
2f5e0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2f5f0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
2f600 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
2f610 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2f620 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
2f630 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
2f640 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2f650 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2f660 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2f670 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2f680 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
2f690 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2f6a0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
2f6b0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
2f6c0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
2f6d0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
2f6e0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2f6f0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2f700 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2f710 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2f720 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f730 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
2f740 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2f750 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
2f760 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2f770 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
2f780 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2f790 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2f7a0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2f7b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2f7c0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2f7d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
2f7e0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
2f7f0 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
2f800 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
2f810 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2f820 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
2f830 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
2f840 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2f850 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2f860 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2f870 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2f880 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
2f890 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
2f8a0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
2f8b0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
2f8c0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
2f8d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
2f8e0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
2f8f0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
2f900 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
2f910 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
2f920 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2f930 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
2f940 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
2f950 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
2f960 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2f970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2f980 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
2f990 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
2f9a0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
2f9b0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
2f9c0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
2f9d0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
2f9e0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
2f9f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2fa00 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2fa10 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
2fa20 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
2fa30 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
2fa40 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
2fa50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2fa60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fa70 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
2fa80 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
2fa90 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
2faa0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2fab0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
2fac0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2fad0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2fae0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
2faf0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2fb00 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2fb10 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2fb20 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2fb30 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2fb40 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
2fb50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fb60 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
2fb70 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2fb80 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
2fb90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2fba0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2fbb0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2fbc0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2fbd0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2fbe0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
2fbf0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2fc00 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2fc10 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2fc20 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
2fc30 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2fc40 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2fc50 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2fc60 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2fc70 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2fc80 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2fc90 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
2fca0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2fcb0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2fcc0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2fcd0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
2fce0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2fcf0 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
2fd00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2fd10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2fd20 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2fd30 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2fd40 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2fd50 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
2fd60 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2fd70 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
2fd80 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2fd90 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
2fda0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2fdb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2fdc0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2fdd0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2fde0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2fdf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fe00 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
2fe10 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2fe20 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2fe30 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2fe40 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
2fe50 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2fe60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2fe70 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2fe80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2fe90 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2fea0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2feb0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
2fec0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2fed0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
2fee0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2fef0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2ff00 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2ff10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ff20 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
2ff30 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
2ff40 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
2ff50 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
2ff60 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
2ff70 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
2ff80 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2ff90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ffa0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
2ffb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2ffc0 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
2ffd0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
2ffe0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
2fff0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
30000 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
30010 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
30020 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
30030 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
30040 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
30050 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
30060 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
30070 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
30080 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
30090 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
300a0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
300b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
300c0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
300d0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
300e0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c  pointer..**.** <
300f0 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e  b>Warning:</b> ^
30100 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
30110 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
30120 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
30130 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
30140 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30150 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e  lue] object.  In
30160 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64   a multithreaded
30170 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a   environment,.**
30180 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
30190 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
301a0 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ject may only be
301b0 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74   used safely wit
301c0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  h.** [sqlite3_bi
301d0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
301e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
301f0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
30200 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
30210 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30220 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
30230 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
30240 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
30250 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
30260 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
30270 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
30280 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
30290 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
302a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
302b0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
302c0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
302d0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62  _bytes()], the b
302e0 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74  ehavior is not t
302f0 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a  hreadsafe..**.**
30300 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
30310 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
30320 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
30330 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
30340 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
30350 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
30360 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
30370 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
30380 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
30390 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
303a0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
303b0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
303c0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
303d0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
303e0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
303f0 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
30400 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
30410 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
30420 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
30430 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
30440 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
30450 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
30460 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
30470 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
30480 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
30490 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
304a0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
304b0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
304c0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
304d0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
304e0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
304f0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
30500 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
30510 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
30520 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
30530 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
30540 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
30550 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
30560 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
30570 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
30580 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
30590 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
305a0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
305b0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
305c0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
305d0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
305e0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
305f0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
30600 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
30610 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
30620 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
30630 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
30640 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
30650 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
30660 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
30670 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
30680 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
30690 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
306a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
306b0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
306c0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
306d0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
306e0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
306f0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
30700 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43   BLOB    <td> [C
30710 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20  AST] to BLOB.** 
30720 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
30730 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30740 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
30750 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
30760 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
30770 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
30780 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
30790 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
307a0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
307b0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
307c0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
307d0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
307e0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
307f0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
30800 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
30810 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
30820 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
30830 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
30840 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
30850 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
30860 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
30870 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
30880 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
30890 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
308a0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
308b0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
308c0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
308d0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
308e0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
308f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
30900 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
30910 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
30920 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
30930 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
30940 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
30950 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
30960 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
30970 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
30980 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
30990 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
309a0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
309b0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
309c0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
309d0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
309e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
309f0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
30a00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30a10 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
30a20 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
30a30 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
30a40 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
30a50 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
30a60 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
30a70 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
30a80 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
30a90 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
30aa0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30ab0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
30ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30ad0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
30ae0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
30af0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
30b00 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
30b10 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
30b20 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
30b30 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
30b40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
30b50 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
30b60 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
30b70 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
30b80 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
30b90 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
30ba0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
30bb0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
30bc0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
30bd0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
30be0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
30bf0 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
30c00 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
30c10 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
30c20 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
30c30 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
30c40 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
30c50 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
30c60 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
30c70 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
30c80 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
30c90 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
30ca0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
30cb0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
30cc0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
30cd0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
30ce0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
30cf0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
30d00 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
30d10 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
30d20 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
30d30 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
30d40 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
30d50 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  est policy is to
30d60 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
30d70 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
30d80 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
30d90 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
30da0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
30db0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30dc0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
30dd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30de0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
30df0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
30e00 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
30e10 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
30e20 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
30e30 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
30e40 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
30e50 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
30e60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30e70 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
30e80 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
30e90 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
30ea0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
30eb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
30ec0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
30ed0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
30ee0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30ef0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
30f00 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
30f10 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
30f20 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
30f30 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
30f40 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
30f50 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
30f60 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
30f70 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
30f80 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
30f90 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
30fa0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
30fb0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
30fc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
30fd0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
30fe0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
30ff0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
31000 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
31010 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
31020 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
31030 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
31040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31050 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
31060 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
31070 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
31080 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
31090 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
310a0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
310b0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
310c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
310d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
310e0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
310f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
31100 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
31110 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
31120 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
31130 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
31140 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
31150 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f  ally.  Do <em>no
31160 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20  t</em> pass the 
31170 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
31180 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
31190 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
311a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
311b0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
311c0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
311d0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
311e0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
311f0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
31200 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
31210 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
31220 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
31230 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
31240 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
31250 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
31260 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
31270 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
31280 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
31290 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
312a0 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
312b0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
312c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
312d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
312e0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
312f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
31300 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
31310 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
31320 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
31330 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
31340 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
31350 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
31360 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31370 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
31380 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
31390 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
313a0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
313b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
313c0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
313d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
313e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
313f0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
31400 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
31410 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
31420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
31430 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
31440 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
31450 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
31460 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
31470 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
31480 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
31490 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
314a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
314b0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
314c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
314d0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
314e0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
314f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
31500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
31510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
31520 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
31530 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
31540 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31550 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
31560 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
31570 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52  ct.** DESTRUCTOR
31580 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31590 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
315a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
315b0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
315c0 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
315d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
315e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
315f0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
31600 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
31610 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
31620 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
31630 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
31640 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
31650 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
31660 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31670 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
31680 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
31690 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
316a0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
316b0 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
316c0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
316d0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
316e0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
316f0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
31700 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
31710 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
31720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31730 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
31740 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
31750 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
31760 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
31770 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
31780 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31790 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
317a0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
317b0 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
317c0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
317d0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
317e0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
317f0 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
31800 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
31810 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
31820 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
31830 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
31840 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
31850 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
31860 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
31870 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31880 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
31890 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
318a0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
318b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
318c0 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
318d0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
318e0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
318f0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
31900 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
31910 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
31920 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
31930 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
31940 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
31950 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
31960 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
31970 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
31980 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
31990 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
319a0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
319b0 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
319c0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
319d0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
319e0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
319f0 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
31a00 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
31a10 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
31a20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
31a30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
31a40 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31a50 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
31a60 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
31a70 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44  Object.** METHOD
31a80 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31a90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31aa0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
31ab0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
31ac0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
31ad0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
31ae0 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
31af0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
31b00 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
31b10 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
31b20 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
31b30 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
31b40 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
31b50 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
31b60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
31b70 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
31b80 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
31b90 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
31ba0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
31bb0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
31bc0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
31bd0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
31be0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
31bf0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
31c00 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
31c10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31c20 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
31c30 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
31c40 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
31c50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
31c60 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
31c70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
31c80 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
31c90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31ca0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
31cb0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
31cc0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
31cd0 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
31ce0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
31cf0 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
31d00 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
31d10 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
31d20 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
31d30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
31d40 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
31d50 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
31d60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
31d70 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
31d80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31d90 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
31da0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
31db0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
31dc0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
31dd0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
31de0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
31df0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
31e00 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
31e10 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
31e20 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
31e30 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
31e40 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
31e50 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
31e60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
31e70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
31e80 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
31e90 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
31ea0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
31eb0 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
31ec0 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
31ed0 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
31ee0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
31ef0 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
31f00 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
31f10 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
31f20 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
31f30 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
31f40 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
31f50 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
31f60 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
31f70 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
31f80 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
31f90 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
31fa0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
31fb0 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
31fc0 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
31fd0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
31fe0 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
31ff0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
32000 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
32010 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
32020 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
32030 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
32040 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
32050 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
32060 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
32070 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
32080 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
32090 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
320a0 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
320b0 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
320c0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
320d0 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
320e0 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
320f0 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
32100 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32110 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
32120 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
32130 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
32140 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32150 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
32160 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
32170 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
32180 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
32190 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
321a0 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
321b0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
321c0 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
321d0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
321e0 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
321f0 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
32200 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
32210 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
32220 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
32230 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
32240 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
32250 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
32260 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
32270 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
32280 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
32290 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
322a0 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
322b0 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
322c0 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
322d0 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
322e0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
322f0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
32300 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
32310 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
32320 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
32330 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
32340 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
32350 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
32360 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
32370 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
32380 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
32390 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
323a0 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
323b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
323c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
323d0 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
323e0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
323f0 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
32400 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
32410 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
32420 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
32430 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
32440 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
32450 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
32460 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
32470 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
32480 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
32490 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
324a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
324b0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
324c0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
324d0 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
324e0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
324f0 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
32500 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
32510 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
32520 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
32530 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
32540 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
32550 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
32560 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
32570 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
32580 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
32590 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
325a0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
325b0 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20  arameters.  The 
325c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
325d0 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61  ld set this para
325e0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c  meter to.** [SQL
325f0 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20  ITE_UTF16LE] if 
32600 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
32610 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
32620 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  kes .** [sqlite3
32630 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
32640 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20  )] on an input, 
32650 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
32660 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d  BE] if the.** im
32670 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
32680 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61  okes [sqlite3_va
32690 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20  lue_text16be()] 
326a0 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a  on an input, or.
326b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
326c0 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  ] if [sqlite3_va
326d0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73  lue_text16()] is
326e0 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54   used, or [SQLIT
326f0 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72  E_UTF8].** other
32700 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65  wise.  ^The same
32710 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61   SQL function ma
32720 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
32730 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
32740 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e  sing.** differen
32750 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  t preferred text
32760 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68   encodings, with
32770 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65   different imple
32780 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a  mentations for.*
32790 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e  * each encoding.
327a0 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
327b0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
327c0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
327d0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
327e0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
327f0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
32800 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
32810 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
32820 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
32830 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sion..**.** ^The
32840 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
32850 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79  r may optionally
32860 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53   be ORed with [S
32870 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
32880 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  TIC].** to signa
32890 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74  l that the funct
328a0 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ion will always 
328b0 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
328c0 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20  result given.** 
328d0 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20  the same inputs 
328e0 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20  within a single 
328f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
32900 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  Most SQL functio
32910 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d  ns are.** determ
32920 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75  inistic.  The bu
32930 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29  ilt-in [random()
32940 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  ] SQL function i
32950 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
32960 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  a.** function th
32970 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d  at is not determ
32980 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51  inistic.  The SQ
32990 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e  Lite query plann
329a0 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a  er is able to.**
329b0 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f   perform additio
329c0 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  nal optimization
329d0 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74  s on determinist
329e0 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f  ic functions, so
329f0 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b   use.** of the [
32a00 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
32a10 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65  STIC] flag is re
32a20 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20  commended where 
32a30 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  possible..**.** 
32a40 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
32a50 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
32a60 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
32a70 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
32a80 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
32a90 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
32aa0 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
32ab0 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
32ac0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
32ad0 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ].)^.**.** ^The 
32ae0 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61  sixth, seventh a
32af0 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65  nd eighth parame
32b00 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
32b10 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
32b20 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
32b30 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
32b40 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
32b50 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
32b60 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
32b70 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
32b80 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
32b90 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
32ba0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
32bb0 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
32bc0 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
32bd0 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70  inters must be p
32be0 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
32bf0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
32c00 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
32c10 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
32c20 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
32c30 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
32c40 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
32c50 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
32c60 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20  LL pointer must 
32c70 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
32c80 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
32c90 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
32ca0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
32cb0 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
32cc0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72  ULL pointers for
32cd0 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
32ce0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73  ion.** callbacks
32cf0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65  ..**.** ^(If the
32d00 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
32d10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
32d20 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
32d30 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
32d40 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74   then it is dest
32d50 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61  ructor for the a
32d60 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
32d70 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65  pointer. .** The
32d80 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69   destructor is i
32d90 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
32da0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
32db0 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62  ted, either by b
32dc0 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64  eing.** overload
32dd0 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64  ed or when the d
32de0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32df0 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20  on closes.)^.** 
32e00 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
32e10 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20  is also invoked 
32e20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  if the call to.*
32e30 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
32e40 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66  _function_v2() f
32e50 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74  ails..** ^When t
32e60 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61  he destructor ca
32e70 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65  llback of the te
32e80 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  nth parameter is
32e90 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20   invoked, it.** 
32ea0 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67  is passed a sing
32eb0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
32ec0 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  h is a copy of t
32ed0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
32ee0 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ata .** pointer 
32ef0 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69  which was the fi
32f00 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  fth parameter to
32f10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32f20 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  function_v2()..*
32f30 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
32f40 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
32f50 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
32f60 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
32f70 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
32f80 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
32f90 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
32fa0 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
32fb0 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
32fc0 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
32fd0 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
32fe0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
32ff0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
33000 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
33010 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
33020 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
33030 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
33040 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
33050 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
33060 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
33070 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
33080 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
33090 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
330a0 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
330b0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
330c0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
330d0 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
330e0 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
330f0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
33100 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
33110 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
33120 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
33130 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
33140 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
33150 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
33160 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
33170 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
33180 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
33190 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
331a0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
331b0 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
331c0 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
331d0 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
331e0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
331f0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
33200 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
33210 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
33220 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
33230 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
33240 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
33250 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
33260 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
33270 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33280 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70  s..**.** ^An app
33290 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
332a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
332b0 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
332c0 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
332d0 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
332e0 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
332f0 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
33300 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
33310 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
33320 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
33330 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
33340 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
33350 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
33360 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69  is running..*/.i
33370 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
33380 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
33390 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
333a0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
333b0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
333c0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
333d0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
333e0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
333f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
33400 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
33410 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
33420 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
33430 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
33440 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
33450 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
33460 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33470 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
33480 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33490 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
334a0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
334b0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
334c0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
334d0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
334e0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
334f0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
33500 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33520 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
33530 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
33540 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
33550 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
33560 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
33570 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
33580 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
33590 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
335a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
335b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
335c0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
335d0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
335e0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
335f0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
33600 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
33610 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
33620 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
33630 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
33640 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
33650 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
33660 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
33670 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
33680 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
33690 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
336a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
336b0 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
336c0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
336d0 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
336e0 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
336f0 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
33700 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
33710 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
33720 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
33730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33740 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
33750 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33  1    /* IMP: R-3
33760 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64  7514-35566 */.#d
33770 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
33780 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20  16LE        2   
33790 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31   /* IMP: R-03371
337a0 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e  -37637 */.#defin
337b0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
337c0 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20          3    /* 
337d0 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31  IMP: R-51971-341
337e0 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  54 */.#define SQ
337f0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
33800 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
33810 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
33820 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
33830 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
33840 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65     5    /* Depre
33850 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  cated */.#define
33860 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
33870 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
33880 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33890 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
338a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
338b0 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a   Function Flags.
338c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
338d0 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65  tants may be ORe
338e0 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20  d together with 
338f0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
33900 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64  UTF8 | preferred
33910 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
33920 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
33930 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
33940 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33950 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ction()], [sqlit
33960 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33970 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
33980 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33990 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  unction_v2()]..*
339a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
339b0 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20  _DETERMINISTIC  
339c0 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43    0x800../*.** C
339d0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
339e0 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
339f0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
33a00 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
33a10 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
33a20 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
33a30 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
33a40 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
33a50 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
33a60 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
33a70 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
33a80 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
33a90 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
33aa0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
33ab0 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
33ac0 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
33ad0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65  functions.  To e
33ae0 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d  ncourage program
33af0 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  mers to avoid.**
33b00 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
33b10 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78  , we will not ex
33b20 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20  plain what they 
33b30 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
33b40 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
33b50 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
33b60 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
33b70 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33b80 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
33b90 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
33ba0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
33bb0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
33bc0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
33bd0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
33be0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
33bf0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
33c00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
33c10 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
33c20 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
33c30 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
33c40 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
33c50 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
33c60 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
33c70 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
33c80 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
33c90 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
33ca0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
33cb0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
33cc0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
33cd0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
33ce0 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
33cf0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
33d00 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
33d10 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
33d20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
33d30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
33d40 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  lue.**.** The C-
33d50 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
33d60 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
33d70 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
33d80 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
33d90 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
33da0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
33db0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
33dc0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
33dd0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
33de0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20   or aggregate.  
33df0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
33e00 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
33e10 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
33e20 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
33e30 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
33e40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
33e50 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
33e60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
33e70 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
33e80 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
33e90 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
33ea0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
33eb0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
33ec0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
33ed0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
33ee0 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
33ef0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
33f00 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
33f10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33f20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
33f30 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
33f40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
33f50 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
33f60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
33f70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
33f80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
33f90 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
33fa0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
33fb0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
33fc0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
33fd0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
33fe0 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
33ff0 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
34000 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34010 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
34020 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
34030 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
34040 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
34050 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
34060 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
34070 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
34080 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
34090 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
340a0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
340b0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
340c0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
340d0 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
340e0 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74   that these rout
340f0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
34100 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
34110 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34120 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
34130 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
34140 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
34150 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
34160 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
34170 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34180 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34190 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
341a0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
341b0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
341c0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
341d0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
341e0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
341f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
34200 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
34210 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34220 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
34230 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
34240 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
34250 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
34260 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
34270 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
34280 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
34290 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
342a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
342b0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
342c0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
342d0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
342e0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
342f0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
34300 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
34310 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
34320 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
34330 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
34340 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
34350 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
34360 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
34370 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
34380 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
34390 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
343a0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
343b0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
343c0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
343d0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
343e0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
343f0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
34400 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
34410 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
34420 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
34430 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
34440 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
34450 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
34460 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
34470 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
34480 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
34490 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
344a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
344b0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
344c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
344d0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
344e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
344f0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
34500 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
34510 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
34520 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
34530 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
34540 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
34550 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
34560 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
34570 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
34580 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
34590 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
345a0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
345b0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
345c0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
345d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
345e0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
345f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
34600 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
34610 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
34620 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
34630 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
34640 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
34650 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
34660 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
34670 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
34680 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34690 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
346a0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
346b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
346c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
346d0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
346e0 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
346f0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
34700 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
34710 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
34720 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
34730 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34740 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34750 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
34760 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34770 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
34780 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
34790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
347a0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
347b0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
347c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
347d0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
347e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
347f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
34800 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
34810 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
34820 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
34830 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
34840 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34850 52 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65  REF: Finding The
34860 20 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20   Subtype Of SQL 
34870 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
34880 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
34890 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
348a0 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28  3_value_subtype(
348b0 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  V) function retu
348c0 72 6e 73 20 74 68 65 20 73 75 62 74 79 70 65 20  rns the subtype 
348d0 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69  for.** an [appli
348e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
348f0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67  QL function] arg
34900 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75  ument V.  The su
34910 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  btype.** informa
34920 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
34930 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74   to pass a limit
34940 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  ed amount of con
34950 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  text from.** one
34960 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
34970 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74   another.  Use t
34980 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
34990 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a  lt_subtype()].**
349a0 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20   routine to set 
349b0 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20  the subtype for 
349c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
349d0 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74   of an SQL funct
349e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
349f0 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f  e makes no use o
34a00 66 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66  f subtype itself
34a10 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73  .  It merely pas
34a20 73 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a  ses the subtype.
34a30 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75  ** from the resu
34a40 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69  lt of one [appli
34a50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
34a60 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74  QL function] int
34a70 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f  o the.** input o
34a80 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e  f another..*/.un
34a90 73 69 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74  signed int sqlit
34aa0 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65  e3_value_subtype
34ab0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34ac0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34ad0 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65  F: Copy And Free
34ae0 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d   SQL Values.** M
34af0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76  ETHOD: sqlite3_v
34b00 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  alue.**.** ^The 
34b10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
34b20 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d  p(V) interface m
34b30 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
34b40 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
34b50 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61  e].** object D a
34b60 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
34b70 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70  nter to that cop
34b80 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  y.  ^The [sqlite
34b90 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65  3_value] returne
34ba0 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65  d.** is a [prote
34bb0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34bc0 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20  ue] object even 
34bd0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
34be0 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  not..** ^The sql
34bf0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
34c00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
34c10 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73  rns NULL if V is
34c20 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a   NULL or if a.**
34c30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
34c40 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  on fails..**.** 
34c50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
34c60 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72  ue_free(V) inter
34c70 66 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73  face frees an [s
34c80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34c90 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73  ject.** previous
34ca0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
34cb0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34cc0 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69  dup()].  ^If V i
34cd0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
34ce0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
34cf0 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
34d00 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
34d10 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76  op..*/.sqlite3_v
34d20 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61  alue *sqlite3_va
34d30 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71  lue_dup(const sq
34d40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
34d50 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  oid sqlite3_valu
34d60 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76  e_free(sqlite3_v
34d70 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
34d80 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
34d90 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
34da0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45  on Context.** ME
34db0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
34dc0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
34dd0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
34de0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
34df0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
34e00 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
34e10 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
34e20 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
34e30 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
34e40 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
34e50 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
34e60 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
34e70 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
34e80 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
34e90 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
34ea0 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
34eb0 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
34ec0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
34ed0 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
34ee0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
34ef0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
34f00 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
34f10 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
34f20 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
34f30 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
34f40 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34f50 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
34f60 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
34f70 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
34f80 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
34f90 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
34fa0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34fb0 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
34fc0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
34fd0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
34fe0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
34ff0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
35000 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
35010 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
35020 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
35030 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
35040 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
35050 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
35060 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
35070 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
35080 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
35090 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
350a0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
350b0 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
350c0 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
350d0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
350e0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
350f0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
35100 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
35110 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
35120 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
35130 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
35140 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
35150 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35160 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
35170 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
35180 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
35190 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66  inter .** when f
351a0 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e  irst called if N
351b0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72   is less than or
351c0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
351d0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a  r if a memory.**
351e0 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
351f0 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
35200 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
35210 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
35220 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
35230 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
35240 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
35250 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
35260 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
35270 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
35280 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
35290 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
352a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
352b0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
352c0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
352d0 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
352e0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
352f0 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
35300 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
35310 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
35320 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74  ion.)^  Within t
35330 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
35340 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d  ck, it is custom
35350 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d  ary to set.** N=
35360 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71  0 in calls to sq
35370 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
35380 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20  context(C,N) so 
35390 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e  that no .** poin
353a0 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tless memory all
353b0 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a  ocations occur..
353c0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
353d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
353e0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
353f0 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
35400 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
35410 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
35420 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
35430 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
35440 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
35450 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
35460 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
35470 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
35480 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
35490 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
354a0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
354b0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
354c0 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
354d0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
354e0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
354f0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
35500 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
35510 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
35520 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
35530 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
35540 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
35550 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
35560 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
35570 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
35580 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
35590 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
355a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
355b0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
355c0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
355d0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
355e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
355f0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
35600 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
35610 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
35620 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
35630 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
35640 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
35650 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
35660 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
35670 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
35680 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
35690 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
356a0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
356b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
356c0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
356d0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
356e0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
356f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
35700 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
35710 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
35720 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
35730 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
35740 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
35750 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
35760 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35770 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
35780 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
35790 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
357a0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
357b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
357c0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
357d0 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
357e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
357f0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
35800 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
35810 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
35820 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35830 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
35840 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
35850 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35860 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
35870 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
35880 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
35890 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
358a0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
358b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
358c0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
358d0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
358e0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
358f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35900 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35910 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
35920 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
35930 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
35940 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
35950 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
35960 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
35970 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ata.** METHOD: s
35980 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
35990 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
359a0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
359b0 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
359c0 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
359d0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
359e0 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
359f0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
35a00 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
35a10 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
35a20 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
35a30 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
35a40 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
35a50 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
35a60 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
35a70 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
35a80 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
35a90 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
35aa0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
35ab0 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
35ac0 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
35ad0 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
35ae0 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  n a regular-expr
35af0 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a  ession matching.
35b00 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
35b10 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
35b20 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
35b30 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
35b40 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  be stored as.** 
35b50 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
35b60 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74  ted with the pat
35b70 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a  tern string.  .*
35b80 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61  * Then as long a
35b90 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  s the pattern st
35ba0 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65  ring remains the
35bb0 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f   same,.** the co
35bc0 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
35bd0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
35be0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
35bf0 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
35c00 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
35c10 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
35c20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
35c30 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
35c40 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
35c50 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
35c60 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
35c70 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
35c80 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
35c90 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
35ca0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
35cb0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
35cc0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35cd0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
35ce0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
35cf0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
35d00 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75  ated with the fu
35d10 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c  nction argument,
35d20 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65   this sqlite3_ge
35d30 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
35d40 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
35d50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
35d60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35d70 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
35d80 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61  C,N,P,X) interfa
35d90 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65  ce saves P as me
35da0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
35db0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
35dc0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
35dd0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35de0 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e  ion.  ^Subsequen
35df0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
35e00 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
35e10 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20  a(C,N) return P 
35e20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65  from the most re
35e30 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cent.** sqlite3_
35e40 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
35e50 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65  P,X) call if the
35e60 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69   metadata is sti
35e70 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e  ll valid or.** N
35e80 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64  ULL if the metad
35e90 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73  ata has been dis
35ea0 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65  carded..** ^Afte
35eb0 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73  r each call to s
35ec0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35ed0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72  ta(C,N,P,X) wher
35ee0 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  e X is not NULL,
35ef0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
35f00 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
35f10 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58  uctor function X
35f20 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20   with parameter 
35f30 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63  P exactly.** onc
35f40 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61  e, when the meta
35f50 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65  data is discarde
35f60 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  d..** SQLite is 
35f70 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20  free to discard 
35f80 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20  the metadata at 
35f90 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64  any time, includ
35fa0 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ing: <ul>.** <li
35fb0 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  > when the corre
35fc0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
35fd0 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
35fe0 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ges, or.** <li> 
35ff0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  when [sqlite3_re
36000 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
36010 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
36020 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  s called for the
36030 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61  .**      SQL sta
36040 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c  tement, or.** <l
36050 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f  i> when sqlite3_
36060 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73  set_auxdata() is
36070 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f   invoked again o
36080 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d  n the same param
36090 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  eter, or.** <li>
360a0 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67   during the orig
360b0 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74  inal sqlite3_set
360c0 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20  _auxdata() call 
360d0 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a  when a memory .*
360e0 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f  *      allocatio
360f0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
36100 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  </ul>)^.**.** No
36110 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c  te the last bull
36120 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  et in particular
36130 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
36140 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74  r X in .** sqlit
36150 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
36160 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65  ,N,P,X) might be
36170 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74   called immediat
36180 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a  ely, before the.
36190 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
361a0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
361b0 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e  ce even returns.
361c0 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f    Hence sqlite3_
361d0 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a  set_auxdata().**
361e0 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65   should be calle
361f0 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f  d near the end o
36200 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
36210 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  mplementation an
36220 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  d the.** functio
36230 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
36240 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65   should not make
36250 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66   any use of P af
36260 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ter.** sqlite3_s
36270 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73  et_auxdata() has
36280 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a   been called..**
36290 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
362a0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
362b0 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
362c0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
362d0 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  for.** function 
362e0 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
362f0 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  are compile-time
36300 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c   constants, incl
36310 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a  uding literal.**
36320 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
36330 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70  ameters] and exp
36340 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65  ressions compose
36350 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e  d from the same.
36360 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
36370 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
36380 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
36390 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
363a0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
363b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
363c0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
363d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
363e0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
363f0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
36400 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
36410 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
36420 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
36430 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
36440 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
36450 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
36460 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
36470 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
36480 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
36490 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
364a0 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
364b0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
364c0 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
364d0 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
364e0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
364f0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
36500 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
36510 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
36520 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
36530 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
36540 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
36550 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
36560 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
36570 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
36580 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
36590 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
365a0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
365b0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
365c0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
365d0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
365e0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
365f0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
36600 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
36610 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
36620 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
36630 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
36640 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
36650 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
36660 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
36670 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
36680 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
36690 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
366a0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
366b0 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ers..*/.typedef 
366c0 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
366d0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
366e0 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
366f0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
36700 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
36710 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
36720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
36730 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
36740 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
36750 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
36760 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
36770 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
36780 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a  An SQL Function.
36790 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
367a0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
367b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
367c0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
367d0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
367e0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
367f0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
36800 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
36810 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
36820 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
36830 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
36840 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
36850 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
36860 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
36870 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
36880 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
36890 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
368a0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
368b0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
368c0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
368d0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
368e0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
368f0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
36900 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
36910 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
36920 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
36930 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
36940 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
36950 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
36960 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36970 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
36980 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
36990 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
369a0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
369b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
369c0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
369d0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
369e0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
369f0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
36a00 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
36a10 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
36a20 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
36a30 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
36a40 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
36a50 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36a60 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20 61  _zeroblob(C,N) a
36a70 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
36a80 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c 4e  t_zeroblob64(C,N
36a90 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
36aa0 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
36ab0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
36ac0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36ad0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42 4c  on to be.** a BL
36ae0 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
36af0 6c 20 7a 65 72 6f 20 62 79 74 65 73 20 61 6e 64  l zero bytes and
36b00 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
36b10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36b20 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
36b30 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
36b40 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
36b50 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
36b60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36b70 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
36b80 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
36b90 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
36ba0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
36bb0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
36bc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36bd0 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
36be0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36bf0 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
36c00 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
36c10 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
36c20 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
36c30 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
36c40 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
36c50 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
36c60 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
36c70 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
36c80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36c90 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
36ca0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
36cb0 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
36cc0 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
36cd0 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
36ce0 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
36cf0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
36d00 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
36d10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
36d20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
36d30 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
36d40 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
36d50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36d60 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
36d70 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
36d80 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
36d90 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
36da0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
36db0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
36dc0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
36dd0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
36de0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
36df0 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
36e00 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
36e10 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
36e20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
36e30 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
36e40 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
36e50 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
36e60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36e70 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
36e80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36e90 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
36ea0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
36eb0 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
36ec0 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
36ed0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
36ee0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
36ef0 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
36f00 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65  message..** ^The
36f10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36f20 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
36f30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36f40 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
36f50 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
36f60 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
36f70 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
36f80 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
36f90 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
36fa0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
36fb0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
36fc0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
36fd0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
36fe0 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
36ff0 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20  t harm..** ^The 
37000 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37010 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
37020 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
37030 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
37040 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
37050 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
37060 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
37070 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65  unction.  ^By de
37080 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
37090 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
370a0 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75  TE_ERROR.  ^A su
370b0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
370c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
370d0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
370e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
370f0 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
37100 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
37110 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
37120 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37130 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
37140 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
37150 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
37160 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
37170 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
37180 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
37190 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67  BLOB is too long
371a0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
371b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
371c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
371d0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
371e0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
371f0 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
37200 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
37210 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
37220 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
37230 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37240 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
37250 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
37260 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
37270 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
37280 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37290 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
372a0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
372b0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
372c0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
372d0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
372e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
372f0 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
37300 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
37310 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
37320 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37330 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37340 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
37350 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
37360 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
37370 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
37380 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
37390 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
373a0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
373b0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
373c0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
373d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
373e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
373f0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
37400 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37410 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
37420 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37430 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
37440 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
37450 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
37460 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
37470 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
37480 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
37490 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
374a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
374b0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
374c0 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
374d0 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
374e0 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
374f0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
37500 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
37510 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
37520 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
37530 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
37540 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ly..** ^The sqli
37550 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36  te3_result_text6
37560 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
37570 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
37580 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70  lue of an.** app
37590 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
375a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
375b0 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e  a text string in
375c0 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20   an encoding.** 
375d0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
375e0 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74   fifth (and last
375f0 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69  ) parameter, whi
37600 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a  ch must be one.*
37610 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  * of [SQLITE_UTF
37620 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
37630 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
37640 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
37650 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53  _UTF16LE]..** ^S
37660 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
37670 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
37680 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37690 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
376a0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
376b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
376c0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
376d0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
376e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
376f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37700 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
37710 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
37720 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
37730 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
37740 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
37750 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
37760 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
37770 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
37780 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
37790 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
377a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
377b0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
377c0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
377d0 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
377e0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
377f0 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
37800 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
37810 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
37820 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
37830 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37840 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
37850 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66  tion result.  If
37860 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
37870 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  er is non-negati
37880 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d  ve, then it.** m
37890 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
378a0 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20  offset into the 
378b0 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65  string where the
378c0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
378d0 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20  would.** appear 
378e0 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  if the string wh
378f0 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  ere NUL terminat
37900 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
37910 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
37920 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e  .** in the strin
37930 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73  g at a byte offs
37940 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  et that is less 
37950 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  than the value o
37960 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72  f the 3rd.** par
37970 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
37980 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
37990 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65  g will contain e
379a0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64  mbedded NULs and
379b0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f   the.** result o
379c0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70  f expressions op
379d0 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e  erating on strin
379e0 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  gs with embedded
379f0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
37a00 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  ed..** ^If the 4
37a10 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
37a20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
37a30 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
37a40 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
37a50 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
37a60 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
37a70 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
37a80 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
37a90 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
37aa0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
37ab0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
37ac0 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
37ad0 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
37ae0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
37af0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
37b00 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
37b10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37b20 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
37b30 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
37b40 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
37b50 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
37b60 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
37b70 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
37b80 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
37b90 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
37ba0 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
37bb0 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
37bc0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
37bd0 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
37be0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
37bf0 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
37c00 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
37c10 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
37c20 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
37c30 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
37c40 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
37c50 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
37c60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37c70 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
37c80 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
37c90 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
37ca0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
37cb0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
37cc0 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
37cd0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
37ce0 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
37cf0 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
37d00 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
37d10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
37d20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
37d30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
37d40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
37d50 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
37d60 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
37d70 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
37d80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37d90 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
37da0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 75 6e  py of the.** [un
37db0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37dc0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
37dd0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
37de0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
37df0 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
37e00 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
37e10 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
37e20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
37e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
37e40 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
37e50 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
37e60 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
37e70 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
37e80 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
37e90 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
37ea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
37eb0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
37ec0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
37ed0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
37ee0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37ef0 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
37f00 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
37f10 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
37f20 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37f30 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
37f40 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
37f50 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
37f60 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
37f70 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
37f80 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
37f90 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
37fa0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
37fb0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
37fc0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
37fd0 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
37fe0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
37ff0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
38000 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
38010 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
38020 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
38030 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
38040 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
38050 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
38060 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38070 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
38080 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
38090 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
380a0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
380b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
380c0 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ob64(sqlite3_con
380d0 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64  text*,const void
380e0 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
380f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
38100 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69  lite3_uint64,voi
38110 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
38120 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
38130 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
38140 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
38150 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
38160 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
38170 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
38180 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
38190 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
381a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
381b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
381c0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
381d0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
381e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
381f0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
38200 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
38210 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
38220 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
38230 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
38240 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
38250 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
38260 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
38270 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
38280 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
38290 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
382a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
382b0 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
382c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
382d0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
382e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
382f0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
38300 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
38310 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38320 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
38330 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
38340 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
38350 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
38360 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
38370 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
38380 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
38390 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c  ,sqlite3_uint64,
383a0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
383b0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
383c0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
383d0 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
383e0 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  ng);.void sqlite
383f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
38400 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38410 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
38420 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
38430 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
38440 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
38450 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
38460 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
38470 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
38480 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
38490 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
384a0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
384b0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
384c0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
384d0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
384e0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
384f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38500 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
38510 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
38520 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
38530 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38540 2a 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73  *, int n);.int s
38550 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
38560 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  roblob64(sqlite3
38570 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
38580 65 33 5f 75 69 6e 74 36 34 20 6e 29 3b 0a 0a 0a  e3_uint64 n);...
38590 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
385a0 53 65 74 74 69 6e 67 20 54 68 65 20 53 75 62 74  Setting The Subt
385b0 79 70 65 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ype Of An SQL Fu
385c0 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44  nction.** METHOD
385d0 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
385e0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
385f0 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79  te3_result_subty
38600 70 65 28 43 2c 54 29 20 66 75 6e 63 74 69 6f 6e  pe(C,T) function
38610 20 63 61 75 73 65 73 20 74 68 65 20 73 75 62 74   causes the subt
38620 79 70 65 20 6f 66 0a 2a 2a 20 74 68 65 20 72 65  ype of.** the re
38630 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 5b 61  sult from the [a
38640 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
38650 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  ed SQL function]
38660 20 77 69 74 68 20 0a 2a 2a 20 5b 73 71 6c 69 74   with .** [sqlit
38670 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 20 74 6f  e3_context] C to
38680 20 62 65 20 74 68 65 20 76 61 6c 75 65 20 54 2e   be the value T.
38690 20 20 4f 6e 6c 79 20 74 68 65 20 6c 6f 77 65 72    Only the lower
386a0 20 38 20 62 69 74 73 20 0a 2a 2a 20 6f 66 20 74   8 bits .** of t
386b0 68 65 20 73 75 62 74 79 70 65 20 54 20 61 72 65  he subtype T are
386c0 20 70 72 65 73 65 72 76 65 64 20 69 6e 20 63 75   preserved in cu
386d0 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 73 20 6f  rrent versions o
386e0 66 20 53 51 4c 69 74 65 3b 0a 2a 2a 20 68 69 67  f SQLite;.** hig
386f0 68 65 72 20 6f 72 64 65 72 20 62 69 74 73 20 61  her order bits a
38700 72 65 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  re discarded..**
38710 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73   The number of s
38720 75 62 74 79 70 65 20 62 79 74 65 73 20 70 72 65  ubtype bytes pre
38730 73 65 72 76 65 64 20 62 79 20 53 51 4c 69 74 65  served by SQLite
38740 20 6d 69 67 68 74 20 69 6e 63 72 65 61 73 65 0a   might increase.
38750 2a 2a 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ** in future rel
38760 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
38770 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
38780 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28  _result_subtype(
38790 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
387a0 2c 75 6e 73 69 67 6e 65 64 20 69 6e 74 29 3b 0a  ,unsigned int);.
387b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
387c0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
387d0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
387e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
387f0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
38800 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
38810 65 6d 6f 76 65 2c 20 6f 72 20