/ Hex Artifact Content
Login

Artifact f623dd30a4fb7df2fb44a2a85e27813d25e486c2:


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 69 6e 73  er, and thus ins
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 6f 66 20 73 71  eter of.** of sq
39c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
39d0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
39e0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
39f0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3a00: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3a10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3a30: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3a40: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3a50: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3a60: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3a70: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3a80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
3a90: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
3aa0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
3ab0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
3ac0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
3ad0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
3ae0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3af0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3b00: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3b10: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3b20: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3b30: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3b40: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3b50: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3b60: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3b70: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3b80: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b90: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ba0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3bb0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3bc0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3bd0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3be0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3c00: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3c10: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c20: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3c30: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3c40: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3c50: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3c60: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3c70: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3c80: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3c90: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3ca0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3cb0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3cc0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3cd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3ce0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3cf0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3d00: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3d10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3d20: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3d30: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3d40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3d50: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3d60: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3d70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3d80: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3d90: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3da0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3db0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3dc0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3dd0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3de0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3df0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3e00: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3e10: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3e20: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3e30: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3e40: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3e50: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3e60: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3e70: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3e80: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3e90: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3ea0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3eb0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3ec0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3ed0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3ee0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3ef0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
3f00: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f10: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f20: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3f30: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f50: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3f70: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
3f80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3f90: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
3fa0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
3fb0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3fc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3fd0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3fe0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3ff0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
4000: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
4010: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
4020: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
4030: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
4040: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
4050: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
4060: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4070: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4080: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
4090: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
40a0: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  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 20                  
40d0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
40e0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
40f0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
4120: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4130: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4140: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4150: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4160: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4170: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  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 20                  
41a0: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
41b0: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
41c0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  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 20 20 20 2f 2a                /*
41f0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
4200: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
4210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
4220: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4250: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4260: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4270: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4290: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
42a0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
42b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
42c0: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
42d0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
42e0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
42f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
4300: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4310: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
4320: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4330: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4340: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4350: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4360: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4370: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4380: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4390: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
43a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
43b0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
43c0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
43d0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
43e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43f0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4400: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
4410: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
4420: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4430: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4440: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4450: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4460: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4470: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4480: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4490: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
44a0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44c0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
44e0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
44f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4500: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4510: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4520: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4530: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4540: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4550: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4560: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4590: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
45a0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
45b0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
45c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
45d0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
45e0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
45f0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4600: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4620: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4630: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4640: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4650: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4660: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4670: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4680: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4690: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
46a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
46b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
46c0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
46d0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
46e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4710: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4720: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4730: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4760: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4770: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4780: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4790: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
47a0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
47b0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
47c0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
47d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
47e0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
47f0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4800: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4810: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4820: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4830: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4840: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4850: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4860: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4870: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4880: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
48a0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
48b0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
48c0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
48d0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
48e0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
48f0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4900: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4920: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4930: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4940: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4960: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4970: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4980: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4990: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
49b0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
49c0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
49d0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
49e0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
49f0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4a00: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4a10: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4a30: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4a40: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4a50: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4a60: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a80: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a90: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4aa0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4ab0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ad0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4ae0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4af0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b10: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4b20: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4b30: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4b40: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4c40: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4c50: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4c60: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4c70: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4c80: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4c90: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4ca0: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4cb0: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4cc0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4cd0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4ce0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4cf0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4d00: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4d10: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4d20: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4d30: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4d40: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4d50: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4d60: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4d70: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4d80: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4d90: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4da0: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
4db0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
4dc0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
4dd0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
4de0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
4df0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
4e00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
4e10: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4e20: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
4e30: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
4e40: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
4e50: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
4e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4e70: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
4e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
4e90: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
4ea0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
4eb0: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
4ec0: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
4ed0: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
4ee0: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
4ef0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
4f00: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
4f10: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
4f20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4f30: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4f40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4f50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4f60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4f70: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4f80: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4fa0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4fb0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4fc0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fd0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ff0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
5000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5010: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5020: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
5030: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
5040: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
5050: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5060: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
5070: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
5080: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
5090: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
50a0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
50b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
50c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
50d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50e0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
50f0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
5110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5120: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
5130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5140: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
5150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5160: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
5170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5180: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
51b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51c0: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
51d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51e0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
51f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5200: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
5210: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5220: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
5230: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5240: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
5250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5260: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
5270: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
5280: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
5290: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52a0: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
52b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52c0: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
52d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52e0: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
52f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5300: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
5310: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5320: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
5330: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5340: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5350: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5360: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5370: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5380: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5390: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53a0: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
53b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53c0: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
53d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53e0: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
53f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5400: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
5410: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5420: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
5430: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5440: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5450: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5460: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5470: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5480: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5490: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54a0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
54b0: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
54c0: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
54d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54e0: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
54f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5500: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
5510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5520: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
5530: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5540: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
5550: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5560: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
5570: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5580: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
5590: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55a0: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
55b0: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
55c0: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
55d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55e0: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
55f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5600: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
5610: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5620: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
5630: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5640: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
5650: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5660: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
5670: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
5680: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5690: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56a0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
56b0: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
56c0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
56d0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
56e0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
56f0: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
5700: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5710: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5720: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5730: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
5740: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5750: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
5760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
5770: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5780: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5790: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
57a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
57b0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
57c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
57d0: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
57e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
57f0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
5800: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5810: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5820: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5830: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
5840: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
5850: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
5860: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5870: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
5880: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
5890: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
58a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58b0: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
58c0: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
58d0: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
58e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58f0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5900: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5910: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5920: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5930: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5940: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5950: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5960: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5980: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5990: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
59a0: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
59b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59c0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
59d0: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
59e0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
59f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5a10: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5a20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5a30: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5a40: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5a50: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5a60: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5a70: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a90: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5ab0: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ad0: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5ae0: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5af0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5b00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5b20: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5b30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b40: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5b50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5b60: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5b70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5b80: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5b90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5ba0: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5bb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5bc0: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5be0: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5bf0: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c00: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5c20: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5c40: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
5c50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
5c60: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
5c70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
5c80: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
5c90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5ca0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5cb0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5cc0: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5cd0: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5ce0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5cf0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5d00: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d10: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5d20: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5d30: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5d40: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5d50: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5d60: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5d70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5d80: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5d90: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5da0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5db0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5dc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5dd0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5de0: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5df0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5e20: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5e30: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5e40: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e50: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5e70: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5e80: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5e90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5eb0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5ec0: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5ed0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5ef0: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5f00: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5f10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5f30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5f40: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5f50: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f60: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5f70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
5f80: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
5f90: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
5fa0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5fc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5fd0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5fe0: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
5ff0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6000: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6010: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6020: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
6030: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
6050: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
6060: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6090: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
60a0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
60d0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
60e0: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6110: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
6120: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
6150: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
6160: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
6170: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6190: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
61a0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
61b0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
61c0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
61d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
61e0: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
61f0: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6200: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6210: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6220: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
6230: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
6240: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
6250: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6260: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6270: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6280: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6290: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
62a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
62d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
62e0: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
62f0: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6300: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6310: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6320: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
6330: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
6340: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
6350: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
6360: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6370: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6380: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6390: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
63a0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
63b0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
63c0: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
63d0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
63e0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
63f0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6400: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6410: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6420: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6430: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6440: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6450: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
6460: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6470: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6480: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6490: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
64a0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
64b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
64c0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
64d0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
64e0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
64f0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6500: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6510: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6520: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6530: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6540: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6550: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
6560: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6570: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6580: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6590: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
65a0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
65b0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
65c0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
65d0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
65e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
65f0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6600: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6610: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6620: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6630: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6640: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6650: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
6660: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6670: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6680: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6690: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
66a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
66b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
66c0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
66d0: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
66e0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
66f0: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6700: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6710: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6720: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6730: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6740: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6750: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
6760: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6770: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6780: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6790: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
67a0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
67b0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
67c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
67d0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
67e0: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
67f0: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
6800: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6810: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
6820: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
6830: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6840: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6850: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6860: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6870: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6880: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6890: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
68a0: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
68b0: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
68c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
68d0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
68e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
68f0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6900: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6910: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6920: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6930: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6940: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6950: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6960: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6970: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6980: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6990: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
69a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
69b0: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
69c0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
69d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
69e0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
69f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a00: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6a10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6a20: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6a30: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6a50: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6a60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6a70: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6a80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6a90: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6aa0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6ab0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6ac0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6ad0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6ae0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6af0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6b00: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6b10: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6b20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6b30: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6b40: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6b60: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6b70: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6b80: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6b90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6ba0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6bb0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6bc0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6bd0: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6be0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6bf0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6c00: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6c10: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6c20: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6c30: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6c40: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6c50: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6c60: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6c70: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6c80: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6c90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6ca0: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6cb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6cc0: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6cd0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6ce0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6cf0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6d00: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6d10: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6d20: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6d30: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6d40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6d50: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6d60: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6d70: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6d80: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6d90: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6da0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6db0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6dc0: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6dd0: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6de0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6df0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6e00: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6e10: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6e20: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6e30: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6e40: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6e50: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6e60: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6e70: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6e80: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
6e90: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
6ea0: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
6eb0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6ec0: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
6ed0: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
6ee0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
6ef0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
6f00: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6f10: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
6f20: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6f30: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
6f40: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
6f50: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
6f60: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
6f70: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
6f80: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
6f90: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
6fa0: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
6fb0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6fc0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6fd0: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
6fe0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
6ff0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
7000: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
7010: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
7020: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
7030: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
7040: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7050: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
7060: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7070: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7080: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7090: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
70a0: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
70b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
70c0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
70d0: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
70e0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
70f0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
7100: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
7110: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
7120: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
7130: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
7140: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7150: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
7160: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7170: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7180: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7190: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
71a0: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
71b0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
71c0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
71d0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
71e0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
71f0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
7200: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
7210: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
7220: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
7230: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
7240: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7250: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
7260: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7270: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7290: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
72a0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
72b0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
72c0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
72d0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
72e0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
72f0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
7300: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
7310: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7320: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
7330: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
7340: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7350: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
7360: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7370: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7380: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7390: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
73a0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
73b0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
73c0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
73d0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
73e0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
73f0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7400: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7410: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
7420: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7430: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7440: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7450: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
7460: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7470: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7480: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7490: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
74a0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
74b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
74c0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
74d0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
74e0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
74f0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7500: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7510: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7520: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
7530: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7540: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7550: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
7560: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7570: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7580: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7590: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
75a0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
75b0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
75c0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
75d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
75e0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
75f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7600: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7610: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
7620: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7630: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7640: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7650: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
7660: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7670: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7680: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7690: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
76a0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
76b0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
76c0: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
76d0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
76e0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
76f0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7700: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7710: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
7720: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
7730: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7740: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7750: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7760: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7770: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7780: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7790: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
77a0: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
77b0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
77c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
77d0: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
77e0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
77f0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7800: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7810: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
7820: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
7830: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7840: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7850: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
7860: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7870: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7880: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7890: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
78a0: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
78b0: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
78c0: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
78d0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
78e0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
78f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7900: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7910: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7920: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7930: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7940: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7950: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
7960: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
7970: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7980: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7990: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
79a0: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
79b0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
79c0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
79d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
79e0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
79f0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7a00: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7a10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7a20: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7a30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a40: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7a50: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7a60: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7a70: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7a80: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7a90: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7aa0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7ab0: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7ac0: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7ad0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7ae0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7af0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7b00: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7b10: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7b20: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7b30: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7b40: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7b50: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7b60: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7b70: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7b80: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7b90: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7ba0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7bb0: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7bc0: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7bd0: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7be0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7bf0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7c00: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7c10: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7c20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7c30: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7c40: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7c50: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7c60: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7c70: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7c80: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7c90: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7ca0: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7cb0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7cc0: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7cd0: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7ce0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7cf0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7d00: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7d10: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7d20: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7d30: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7d40: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7d50: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7d60: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7d70: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7d80: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7d90: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7da0: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7db0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7dc0: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7dd0: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7de0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7df0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7e00: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7e10: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7e20: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7e30: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7e40: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7e50: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7e60: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7e70: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7e80: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7e90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7ea0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7eb0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7ec0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7ed0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7ee0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7ef0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7f00: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7f10: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7f20: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7f30: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
7f40: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7f50: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
7f60: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
7f70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
7f80: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
7f90: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
7fa0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
7fb0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
7fc0: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
7fd0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
7fe0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
7ff0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
8000: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8010: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
8020: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
8030: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8040: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8050: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8060: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8070: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8080: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8090: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
80a0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
80b0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
80c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80d0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
80e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
80f0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
8100: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8110: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
8120: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8130: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8140: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8150: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8160: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8170: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8180: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8190: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
81a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
81b0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
81c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
81d0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
81e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
81f0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
8200: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8210: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
8220: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8230: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8240: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8250: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8260: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8270: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8280: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8290: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
82a0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
82b0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
82c0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
82d0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
82e0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
82f0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8300: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8310: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8320: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8330: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8340: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8350: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8360: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8370: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8380: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8390: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
83a0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
83b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
83c0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
83d0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
83e0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
83f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8400: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8410: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8420: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8430: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8440: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8450: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8460: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
8470: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8480: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8490: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
84a0: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
84b0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
84c0: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
84d0: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
84e0: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
84f0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8500: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8510: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8520: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
8530: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
8540: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
8550: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
8560: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
8570: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8580: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8590: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
85a0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
85b0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
85c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
85d0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
85e0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
85f0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8600: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8610: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8620: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8630: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8640: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8650: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
8660: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
8670: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8680: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8690: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
86a0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
86b0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
86c0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
86d0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
86e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
86f0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8700: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8710: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8720: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
8730: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
8740: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8750: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
8760: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8770: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8780: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8790: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
87a0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
87b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
87c0: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
87d0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
87e0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
87f0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8800: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8810: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8820: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8830: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8840: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8850: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8860: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8870: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8880: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8890: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
88a0: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
88b0: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
88c0: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
88d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
88e0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
88f0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8900: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8910: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8920: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8930: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8940: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8950: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8960: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8970: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8980: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8990: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
89a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
89b0: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
89c0: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
89d0: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
89e0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
89f0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8a00: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8a10: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8a20: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8a30: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8a40: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8a50: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8a60: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8a70: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8a80: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8a90: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8aa0: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8ab0: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8ac0: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8ad0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8ae0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8af0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8b00: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8b10: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8b20: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8b30: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8b40: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8b50: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8b60: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8b70: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8b80: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8b90: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8ba0: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8bb0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8bc0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8bd0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8be0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8bf0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8c00: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8c10: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8c20: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8c30: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8c40: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8c50: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8c60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8c70: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8c80: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8c90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8ca0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8cb0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8cc0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8cd0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8ce0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8cf0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8d00: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8d10: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8d20: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8d30: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8d40: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8d50: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8d60: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8d70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8d80: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8d90: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8da0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8db0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8dc0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8dd0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8de0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8df0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8e00: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8e10: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8e20: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8e30: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8e40: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8e50: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8e60: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8e70: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8e80: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8e90: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8ea0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8eb0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8ec0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8ed0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8ee0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8ef0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8f00: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8f10: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8f20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8f30: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8f40: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8f50: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8f60: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8f70: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8f80: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8f90: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8fa0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8fb0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8fc0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8fd0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8fe0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8ff0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9000: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9010: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
9020: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
9030: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
9040: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
9050: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
9060: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
9070: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
9080: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9090: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
90a0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
90b0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
90c0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
90d0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
90e0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
90f0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9100: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9110: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9120: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9130: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9140: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9150: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9160: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9170: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9180: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9190: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
91a0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
91b0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
91c0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
91d0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
91e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
91f0: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
9200: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9210: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9220: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
9230: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9240: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9250: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9260: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9270: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9280: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9290: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
92a0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
92b0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
92c0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
92d0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
92e0: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
92f0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
9300: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9310: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9320: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9330: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9340: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9350: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9360: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9370: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9380: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9390: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
93a0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
93b0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
93c0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
93d0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
93e0: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
93f0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
9400: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9410: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9420: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9430: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
9440: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9450: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9460: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9470: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9480: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9490: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
94a0: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
94b0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
94c0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
94d0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
94e0: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
94f0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
9500: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9510: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9520: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9530: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9540: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9550: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9560: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9570: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9580: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9590: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
95a0: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
95b0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
95c0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
95d0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
95e0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
95f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9600: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9610: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9620: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9630: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
9640: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9650: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9660: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9670: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9680: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9690: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
96a0: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
96b0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
96c0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
96d0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
96e0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
96f0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
9700: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9710: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9720: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9730: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
9740: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9750: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9760: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9770: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9780: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9790: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
97a0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
97b0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
97c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
97d0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
97e0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
97f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9800: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9810: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9820: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9830: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9840: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9850: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9860: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9870: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9880: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9890: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
98a0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
98b0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
98c0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
98d0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
98e0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
98f0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9900: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9910: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9920: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9930: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9940: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9950: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9960: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9970: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9980: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9990: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
99a0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
99b0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
99c0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
99d0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
99e0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
99f0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9a00: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9a10: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9a20: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9a30: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9a40: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9a50: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9a60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9a70: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9a80: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9a90: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9aa0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9ab0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9ac0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9ad0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9ae0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9af0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9b00: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9b10: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9b20: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9b30: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9b40: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9b50: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9b60: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9b70: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9b80: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9b90: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9ba0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9bb0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9bc0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9bd0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9be0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9bf0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9c00: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9c10: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9c20: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9c30: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9c40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9c50: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9c60: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9c70: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9c80: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9c90: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9ca0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9cb0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9cc0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9cd0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9ce0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9cf0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9d00: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9d10: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9d20: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9d30: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9d40: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9d50: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9d60: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9d70: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9d80: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9d90: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9da0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9db0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9dc0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9dd0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9de0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9df0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9e00: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9e10: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9e20: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9e30: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9e40: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9e50: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9e60: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9e70: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9e80: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9e90: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9ea0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9eb0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9ec0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9ee0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9ef0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9f00: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9f10: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9f20: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9f30: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9f40: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9f50: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9f60: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9f70: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9f80: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9f90: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9fa0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9fb0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9fc0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9fd0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9fe0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9ff0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a000: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a010: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a020: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a030: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a040: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a050: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a060: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a070: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a080: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a090: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a0a0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a0b0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a0c0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a0d0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a0e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a0f0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a100: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a110: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a120: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a130: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a140: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a150: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a160: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a170: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a180: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a190: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a1a0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a1b0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a1c0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a1d0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a1e0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a1f0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a200: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a210: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a220: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a230: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a240: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a250: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a260: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a270: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a280: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a290: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a2a0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a2b0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a2c0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a2d0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a2e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a2f0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a300: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a310: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a320: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a330: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a340: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a350: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a360: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a370: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a380: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a390: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a3a0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a3b0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a3c0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a3d0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a3e0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a3f0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a400: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a410: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a420: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a430: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a440: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a450: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a460: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a470: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a480: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a490: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a4a0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a4b0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a4c0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a4d0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a4e0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a4f0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a500: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a510: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a520: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a530: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a540: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a550: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a560: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a570: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a580: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a590: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a5a0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a5b0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a5c0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a5d0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a5e0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a5f0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a600: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a610: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a620: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a630: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a640: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a650: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a660: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a670: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a680: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a690: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a6a0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a6b0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a6c0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a6d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a6e0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a6f0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a700: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a710: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a720: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a730: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a740: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a750: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a760: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a770: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a780: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a790: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a7a0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a7b0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a7c0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a7d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a7e0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a7f0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a800: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a810: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a820: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a830: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a840: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a850: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a860: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a870: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a880: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a890: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a8a0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a8b0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a8c0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a8d0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a8e0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a8f0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a900: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a910: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a920: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a930: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a940: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a950: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a960: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a970: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a980: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a990: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a9a0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a9b0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a9c0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a9d0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a9e0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a9f0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
aa00: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
aa10: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
aa20: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
aa30: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
aa40: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
aa50: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
aa60: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
aa70: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
aa80: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
aa90: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
aaa0: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
aab0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
aac0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
aad0: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
aae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
aaf0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ab00: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
ab10: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
ab20: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
ab30: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
ab40: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
ab50: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
ab60: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
ab70: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
ab80: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
ab90: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
aba0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
abb0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
abc0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
abd0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
abe0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
abf0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
ac00: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
ac10: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
ac20: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
ac30: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
ac40: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
ac50: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
ac60: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
ac70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ac80: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
ac90: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
aca0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
acb0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
acc0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
acd0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
ace0: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
acf0: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
ad00: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ad10: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ad20: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ad30: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ad40: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ad50: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ad60: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
ad70: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ad80: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
ad90: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ada0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
adb0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
adc0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
add0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
ade0: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
adf0: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
ae00: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
ae10: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
ae20: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
ae30: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
ae40: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
ae50: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
ae60: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
ae70: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
ae80: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
ae90: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
aea0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
aeb0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
aec0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
aed0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
aee0: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
aef0: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
af00: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
af10: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
af20: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
af30: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
af40: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
af50: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
af60: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
af70: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
af80: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
af90: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
afa0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
afb0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
afc0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
afd0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
afe0: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
aff0: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b000: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b010: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b020: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b030: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b040: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b050: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b060: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b070: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b080: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b090: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b0a0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b0b0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b0c0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b0d0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b0e0: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b0f0: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b100: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b110: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b120: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b130: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b140: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b150: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b160: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b170: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b180: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b190: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b1a0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b1b0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b1c0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b1d0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b1e0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b1f0: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b200: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b210: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b220: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b230: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b240: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b250: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b260: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b270: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b280: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b290: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b2a0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b2b0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b2c0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b2d0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b2e0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b2f0: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b300: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b310: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b320: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b330: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b340: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b350: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b360: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b370: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b380: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b390: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b3a0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b3b0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b3c0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b3d0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b3e0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b3f0: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b400: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b410: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b420: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b430: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b440: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b450: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b460: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b470: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b480: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b490: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b4a0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b4b0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
b4c0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
b4d0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
b4e0: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
b4f0: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
b500: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
b510: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
b520: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
b530: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
b540: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b550: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
b560: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
b570: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
b580: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
b590: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
b5a0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
b5b0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
b5c0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
b5d0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
b5e0: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
b5f0: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
b600: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
b610: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
b620: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
b630: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
b640: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
b650: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b660: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b670: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
b680: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b690: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b6a0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
b6b0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
b6c0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
b6d0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
b6e0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
b6f0: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
b700: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
b710: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
b720: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
b730: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
b740: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
b750: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b760: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
b770: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
b780: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
b790: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
b7a0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b7b0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
b7c0: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
b7d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
b7e0: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
b7f0: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
b800: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
b810: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
b820: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
b830: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
b840: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
b850: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
b860: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
b870: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
b880: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
b890: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
b8a0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
b8b0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
b8c0: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
b8d0: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
b8e0: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
b8f0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
b900: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
b910: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
b920: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b930: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
b940: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b950: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
b960: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
b970: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
b980: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
b990: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
b9a0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
b9b0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
b9c0: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
b9d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
b9e0: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
b9f0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
ba00: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
ba10: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
ba20: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
ba30: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
ba40: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
ba50: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
ba60: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
ba70: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
ba80: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20  is opcode.  .** 
ba90: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
baa0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
bab0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
bac0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
bad0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
bae0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
baf0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
bb00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
bb10: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bb20: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
bb30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
bb40: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
bb50: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
bb60: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
bb70: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
bb80: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
bb90: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
bba0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
bbb0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
bbc0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
bbd0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
bbe0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
bbf0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
bc00: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
bc10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bc20: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
bc30: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
bc40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bc50: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
bc60: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
bc70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bc80: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
bc90: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
bca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bcb0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
bcc0: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
bcd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bce0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
bcf0: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
bd00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bd10: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
bd20: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
bd30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bd40: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
bd50: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
bd60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
bd70: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
bd80: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
bd90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
bda0: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
bdb0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
bdc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
bdd0: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
bde0: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
bdf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
be00: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
be10: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
be20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
be30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
be40: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
be50: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
be60: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
be70: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
be80: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
be90: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
bea0: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
beb0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
bec0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
bed0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
bee0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
bef0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
bf00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf10: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
bf20: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
bf30: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
bf40: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
bf50: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
bf60: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
bf70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
bf80: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
bf90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
bfa0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bfb0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
bfc0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
bfd0: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
bfe0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
bff0: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
c000: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
c010: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c020: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
c030: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
c040: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
c050: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
c060: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
c070: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
c080: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
c090: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
c0a0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c0b0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c0c0: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c0d0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c0e0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c0f0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c100: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c110: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c120: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c130: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c140: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c150: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c160: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c170: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c180: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c190: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c1a0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
c1b0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
c1c0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
c1d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c1e0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
c1f0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
c200: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
c210: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
c220: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
c230: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
c240: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
c250: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
c260: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
c270: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
c280: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
c290: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
c2a0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
c2b0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
c2c0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
c2d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
c2e0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
c2f0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
c300: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
c310: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
c320: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
c330: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
c340: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
c350: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
c360: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
c370: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
c380: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
c390: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
c3a0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
c3b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
c3c0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
c3d0: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
c3e0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
c3f0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
c400: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
c410: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
c420: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
c430: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
c440: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
c450: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c460: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
c470: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
c480: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
c490: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
c4a0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
c4b0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
c4c0: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
c4d0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
c4e0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
c4f0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
c500: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
c510: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
c520: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
c530: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
c540: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
c550: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
c560: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
c570: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
c580: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
c590: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
c5a0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
c5b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c5c0: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
c5d0: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
c5e0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
c5f0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c600: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
c610: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
c620: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
c630: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c640: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
c650: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
c660: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
c670: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c680: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
c690: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
c6a0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
c6b0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
c6c0: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
c6d0: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
c6e0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
c6f0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
c700: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
c710: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
c720: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
c730: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
c740: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
c750: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
c760: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
c770: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
c780: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
c790: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
c7a0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
c7b0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
c7c0: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
c7d0: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
c7e0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
c7f0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
c800: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
c810: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
c820: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c830: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
c840: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
c850: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
c860: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
c870: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
c880: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
c890: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
c8a0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
c8b0: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
c8c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c8d0: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
c8e0: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
c8f0: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
c900: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
c910: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
c920: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
c930: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
c940: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
c950: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
c960: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
c970: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
c980: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
c990: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
c9a0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
c9b0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
c9c0: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
c9d0: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
c9e0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
c9f0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
ca00: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
ca10: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
ca20: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
ca30: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
ca40: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
ca50: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
ca60: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
ca70: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
ca80: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
ca90: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
caa0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
cab0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
cac0: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
cad0: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
cae0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
caf0: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
cb00: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
cb10: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
cb20: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
cb30: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
cb40: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cb50: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
cb60: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
cb70: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
cb80: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
cb90: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
cba0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
cbb0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
cbc0: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
cbd0: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
cbe0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
cbf0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
cc00: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
cc10: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
cc20: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
cc30: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
cc40: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
cc50: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
cc60: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
cc70: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
cc80: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
cc90: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
cca0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
ccb0: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
ccc0: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
ccd0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
cce0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
ccf0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
cd00: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
cd10: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
cd20: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
cd30: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
cd40: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
cd50: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
cd60: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
cd70: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
cd80: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
cd90: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
cda0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
cdb0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
cdc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
cdd0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
cde0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
cdf0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
ce00: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ce10: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
ce20: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ce30: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
ce40: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ce50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
ce60: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
ce70: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
ce80: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
ce90: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
cea0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
ceb0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
cec0: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
ced0: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
cee0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
cef0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
cf00: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
cf10: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
cf20: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
cf30: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
cf40: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
cf50: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
cf60: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
cf70: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
cf80: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
cf90: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
cfa0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
cfb0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
cfc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
cfd0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
cfe0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
cff0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
d000: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
d010: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
d020: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
d030: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
d040: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
d050: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
d060: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
d070: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
d080: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
d090: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
d0a0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
d0b0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
d0c0: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
d0d0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
d0e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d0f0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
d100: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
d110: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
d120: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
d130: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d140: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
d150: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
d160: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
d170: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
d180: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
d190: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d1a0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
d1b0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
d1c0: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
d1d0: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
d1e0: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
d1f0: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
d200: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
d210: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
d220: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
d230: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
d240: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
d250: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
d260: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
d270: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
d280: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
d290: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
d2a0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
d2b0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
d2c0: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
d2d0: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
d2e0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
d2f0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
d300: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
d310: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d320: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
d330: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
d340: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
d350: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
d360: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
d370: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
d380: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
d390: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
d3a0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
d3b0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
d3c0: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
d3d0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
d3e0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
d3f0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
d400: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
d410: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
d420: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
d430: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
d440: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
d450: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
d460: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
d470: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
d480: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
d490: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
d4a0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
d4b0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
d4c0: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
d4d0: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
d4e0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d4f0: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
d500: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d510: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
d520: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
d530: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
d540: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
d550: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
d560: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
d570: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
d580: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
d590: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
d5a0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
d5b0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
d5c0: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
d5d0: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
d5e0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
d5f0: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
d600: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
d610: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
d620: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
d630: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
d640: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
d650: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
d660: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d670: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
d680: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
d690: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
d6a0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d6b0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
d6c0: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d6d0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
d6e0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
d6f0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d700: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
d710: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
d720: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
d730: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
d740: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
d750: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
d760: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
d770: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
d780: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
d790: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
d7a0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
d7b0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
d7c0: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
d7d0: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
d7e0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
d7f0: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
d800: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
d810: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
d820: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d830: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
d840: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
d850: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
d860: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
d870: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
d880: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
d890: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
d8a0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
d8b0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
d8c0: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
d8d0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
d8e0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
d8f0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
d900: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
d910: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d920: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
d930: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
d940: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
d950: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
d960: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
d970: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
d980: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
d990: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
d9a0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
d9b0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
d9c0: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
d9d0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
d9e0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
d9f0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
da00: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
da10: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
da20: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
da30: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
da40: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
da50: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
da60: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
da70: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
da80: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
da90: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
daa0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
dab0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
dac0: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
dad0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
dae0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
daf0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
db00: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
db10: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
db20: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
db30: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
db40: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
db50: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
db60: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
db70: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
db80: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
db90: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
dba0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
dbb0: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
dbc0: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
dbd0: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
dbe0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
dbf0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
dc00: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
dc10: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
dc20: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dc30: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
dc40: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
dc50: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
dc60: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
dc70: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
dc80: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
dc90: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
dca0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
dcb0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
dcc0: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
dcd0: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
dce0: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
dcf0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
dd00: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
dd10: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
dd20: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
dd30: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
dd40: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
dd50: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
dd60: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
dd70: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
dd80: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
dd90: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
dda0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
ddb0: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
ddc0: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
ddd0: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
dde0: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
ddf0: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
de00: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
de10: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
de20: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
de30: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
de40: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
de50: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
de60: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
de70: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
de80: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
de90: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
dea0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
deb0: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
dec0: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
ded0: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
dee0: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
def0: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
df00: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
df10: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
df20: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
df30: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
df40: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
df50: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
df60: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
df70: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
df80: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
df90: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
dfa0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
dfb0: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
dfc0: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
dfd0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
dfe0: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
dff0: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
e000: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
e010: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
e020: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
e030: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
e040: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
e050: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
e060: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
e070: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
e080: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
e090: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
e0a0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
e0b0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
e0c0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
e0d0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
e0e0: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
e0f0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
e100: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
e110: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
e120: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
e130: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
e140: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
e150: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
e160: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
e170: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
e180: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
e190: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
e1a0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
e1b0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
e1c0: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
e1d0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
e1e0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
e1f0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
e200: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
e210: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
e220: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
e230: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
e240: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e250: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e260: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
e270: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
e280: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
e290: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
e2a0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
e2b0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e2c0: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
e2d0: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
e2e0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
e2f0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e300: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
e310: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
e320: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
e330: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
e340: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e350: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
e360: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
e370: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
e380: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e390: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
e3a0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
e3b0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
e3c0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e3d0: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
e3e0: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
e3f0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
e400: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
e410: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
e420: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
e430: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
e440: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
e450: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
e460: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
e470: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
e480: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
e490: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
e4a0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
e4b0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
e4c0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e4d0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e4e0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
e4f0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
e500: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e510: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
e520: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e530: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e540: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
e550: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e560: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
e570: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
e580: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
e590: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
e5a0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
e5b0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e5c0: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
e5d0: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
e5e0: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
e5f0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e600: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e610: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
e620: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e630: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
e640: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
e650: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
e660: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
e670: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
e680: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e690: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e6a0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
e6b0: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
e6c0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
e6d0: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
e6e0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e6f0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e700: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
e710: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
e720: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
e730: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e740: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
e750: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e760: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e770: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
e780: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e790: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
e7a0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
e7b0: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
e7c0: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
e7d0: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
e7e0: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
e7f0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
e800: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
e810: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
e820: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
e830: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
e840: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
e850: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
e860: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
e870: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
e880: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
e890: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e8a0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
e8b0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
e8c0: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
e8d0: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
e8e0: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
e8f0: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
e900: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
e910: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e920: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
e930: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
e940: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
e950: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
e960: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
e970: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e980: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
e990: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
e9a0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
e9b0: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
e9c0: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
e9d0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
e9e0: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
e9f0: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
ea00: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
ea10: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
ea20: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
ea30: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
ea40: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ea50: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
ea60: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
ea70: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
ea80: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
ea90: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
eaa0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
eab0: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
eac0: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
ead0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
eae0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
eaf0: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
eb00: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
eb10: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
eb20: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
eb30: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
eb40: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
eb50: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
eb60: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
eb70: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
eb80: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
eb90: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
eba0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
ebb0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ebc0: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
ebd0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ebe0: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
ebf0: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
ec00: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
ec10: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
ec20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ec30: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
ec40: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
ec50: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
ec60: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
ec70: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
ec80: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
ec90: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
eca0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
ecb0: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
ecc0: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
ecd0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
ece0: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
ecf0: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
ed00: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
ed10: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
ed20: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
ed30: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
ed40: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
ed50: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ed60: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
ed70: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
ed80: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
ed90: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
eda0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
edb0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
edc0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
edd0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
ede0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
edf0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ee00: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ee10: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
ee20: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
ee30: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
ee40: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
ee50: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
ee60: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
ee70: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
ee80: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
ee90: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
eea0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
eeb0: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
eec0: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
eed0: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
eee0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
eef0: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
ef00: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
ef10: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
ef20: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
ef30: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
ef40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
ef50: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
ef60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
ef70: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
ef80: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
ef90: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
efa0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
efb0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
efc0: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
efd0: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
efe0: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
eff0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f000: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
f010: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
f020: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
f030: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
f040: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
f050: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
f060: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
f070: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
f080: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
f090: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
f0a0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
f0b0: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
f0c0: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
f0d0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
f0e0: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
f0f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f100: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
f110: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f120: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f130: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f140: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
f150: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
f160: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
f170: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f180: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
f190: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
f1a0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
f1b0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
f1c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f1d0: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
f1e0: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
f1f0: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
f200: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
f210: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
f220: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
f230: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
f240: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
f250: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
f260: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
f270: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
f280: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
f290: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
f2a0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
f2b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f2c0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f2d0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
f2e0: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
f2f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f300: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f310: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
f320: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
f330: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
f340: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
f350: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
f360: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
f370: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
f380: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
f390: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
f3a0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
f3b0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
f3c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f3d0: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
f3e0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
f3f0: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
f400: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
f410: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
f420: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f430: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
f440: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
f450: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f460: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
f470: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f480: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
f490: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f4a0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
f4b0: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
f4c0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f4d0: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
f4e0: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
f4f0: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
f500: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
f510: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f520: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
f530: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
f540: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
f550: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
f560: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
f570: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
f580: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
f590: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
f5a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
f5b0: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
f5c0: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
f5d0: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
f5e0: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
f5f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f600: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
f610: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
f620: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
f630: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
f640: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
f650: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
f660: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f670: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
f680: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
f690: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f6a0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
f6b0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f6c0: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
f6d0: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
f6e0: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
f6f0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
f700: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
f710: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f720: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
f730: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
f740: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
f750: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
f760: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
f770: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
f780: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
f790: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
f7a0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
f7b0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
f7c0: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
f7d0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
f7e0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
f7f0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
f800: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
f810: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
f820: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f830: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f840: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
f850: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
f860: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
f870: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
f880: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
f890: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
f8a0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
f8b0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
f8c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f8d0: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
f8e0: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
f8f0: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
f900: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f910: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
f920: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
f930: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
f940: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
f950: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
f960: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
f970: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
f980: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
f990: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
f9a0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
f9b0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
f9c0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
f9d0: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
f9e0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
f9f0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
fa00: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
fa10: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fa20: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
fa30: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
fa40: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
fa50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fa60: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
fa70: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
fa80: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
fa90: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
faa0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
fab0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
fac0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
fad0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
fae0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
faf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
fb00: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
fb10: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
fb20: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fb30: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
fb40: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
fb50: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
fb60: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
fb70: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
fb80: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
fb90: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
fba0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
fbb0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
fbc0: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
fbd0: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
fbe0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
fbf0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
fc00: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
fc10: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
fc20: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
fc30: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
fc40: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
fc50: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fc60: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
fc70: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
fc80: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fc90: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
fca0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
fcb0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
fcc0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
fcd0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
fce0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
fcf0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
fd00: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
fd10: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
fd20: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
fd30: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
fd40: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
fd50: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
fd60: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
fd70: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
fd80: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
fd90: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
fda0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
fdb0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
fdc0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
fdd0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
fde0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
fdf0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fe00: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
fe10: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
fe20: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
fe30: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
fe40: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
fe50: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
fe60: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
fe70: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
fe80: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
fe90: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
fea0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
feb0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
fec0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
fed0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fee0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
fef0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ff00: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
ff10: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ff20: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
ff30: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
ff40: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
ff50: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
ff60: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
ff70: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
ff80: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
ff90: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
ffa0: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
ffb0: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
ffc0: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
ffd0: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
ffe0: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
fff0: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
10000 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
10010 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
10020 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
10030 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
10040 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
10050 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
10060 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
10070 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
10080 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
10090 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
100a0 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
100b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
100c0 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
100d0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
100e0 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
100f0 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
10100 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
10110 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10120 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
10130 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
10140 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
10150 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
10160 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
10170 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
10180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10190 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
101a0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
101b0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
101c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
101d0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
101e0 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
101f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10200 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
10210 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
10220 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
10230 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
10240 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
10250 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
10260 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
10270 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
10280 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
10290 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
102a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
102b0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
102c0 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
102d0 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
102e0 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
102f0 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
10300 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
10310 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
10320 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10330 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
10340 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
10350 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
10360 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
10370 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10380 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
10390 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
103a0 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
103b0 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
103c0 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
103d0 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
103e0 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
103f0 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
10400 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
10410 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
10420 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
10430 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
10440 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
10450 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
10460 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
10470 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10480 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
10490 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
104a0 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
104b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
104c0 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
104d0 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
104e0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
104f0 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
10500 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
10510 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
10520 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
10530 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
10540 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
10550 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
10560 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10570 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
10580 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10590 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
105a0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
105b0 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
105c0 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
105d0 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
105e0 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
105f0 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
10600 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
10610 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
10620 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
10630 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
10640 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
10650 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
10660 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
10670 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
10680 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
10690 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
106a0 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
106b0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
106c0 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
106d0 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
106e0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
106f0 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
10700 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
10710 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
10720 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10730 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
10740 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
10750 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
10760 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
10770 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10780 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
10790 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
107a0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
107b0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
107c0 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
107d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
107e0 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
107f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10800 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
10810 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
10820 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
10830 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
10840 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
10850 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
10860 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
10870 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
10880 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
10890 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
108a0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
108b0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
108c0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
108d0 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
108e0 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
108f0 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
10900 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
10910 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
10920 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
10930 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
10940 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
10950 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
10960 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
10970 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
10980 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
10990 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
109a0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
109b0 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
109c0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
109d0 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
109e0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
109f0 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
10a00 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
10a10 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
10a20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
10a30 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
10a40 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
10a50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10a60 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
10a70 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
10a80 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
10a90 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
10aa0 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
10ab0 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
10ac0 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
10ad0 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
10ae0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
10af0 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
10b00 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
10b10 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
10b20 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
10b30 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
10b40 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
10b50 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
10b60 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
10b70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10b80 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68  onfig()] when th
10b90 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
10ba0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51  option is.** [SQ
10bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10bc0 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  OC] or [SQLITE_C
10bd0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
10be0 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69  .  .** By creati
10bf0 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
10c00 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
10c10 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
10c20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
10c30 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
10c40 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64  IG_MALLOC]).** d
10c50 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
10c60 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ion, an applicat
10c70 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
10c80 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
10c90 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10ca0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f  ion subsystem fo
10cb0 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
10cc0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a  for all of its.*
10cd0 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  * dynamic memory
10ce0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
10cf0 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
10d00 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61  omes with severa
10d10 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  l [built-in memo
10d20 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a  ry allocators].*
10d30 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65  * that are perfe
10d40 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
10d50 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
10d60 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
10d70 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
10d80 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
10d90 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
10da0 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
10db0 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
10dc0 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
10dd0 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
10de0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
10df0 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
10e00 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
10e10 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
10e20 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
10e30 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
10e40 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
10e50 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
10e60 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
10e70 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
10e80 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
10e90 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
10ea0 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
10eb0 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
10ec0 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
10ed0 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
10ee0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
10ef0 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63  Malloc, xRealloc
10f00 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  , and xFree meth
10f10 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
10f20 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
10f30 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
10f40 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
10f50 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
10f60 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
10f70 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
10f80 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73  ntees that the s
10f90 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
10fa0 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73  o.** xRealloc is
10fb0 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20   always a value 
10fc0 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72  returned by a pr
10fd0 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75  ior call to xRou
10fe0 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  ndup..**.** xSiz
10ff0 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
11000 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
11010 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
11020 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
11030 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
11040 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
11050 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
11060 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
11070 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
11080 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
11090 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
110a0 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
110b0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
110c0 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
110d0 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
110e0 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
110f0 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
11100 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11110 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
11120 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
11130 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
11140 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
11150 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
11160 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
11170 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
11180 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
11190 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
111a0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
111b0 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
111c0 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
111d0 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d  of 2..** Every m
111e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
111f0 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20   request coming 
11200 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69  in through [sqli
11210 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
11220 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
11230 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61  lloc()] first ca
11240 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49  lls xRoundup.  I
11250 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72  f xRoundup retur
11260 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63  ns 0, .** that c
11270 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73  auses the corres
11280 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61  ponding memory a
11290 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69  llocation to fai
112a0 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  l..**.** The xIn
112b0 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
112c0 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
112d0 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72   allocator.  For
112e0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
112f0 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
11300 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
11310 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
11320 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
11330 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
11340 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
11350 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
11360 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
11370 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
11380 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
11390 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
113a0 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
113b0 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
113c0 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
113d0 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
113e0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
113f0 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
11400 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
11410 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
11420 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
11430 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
11440 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
11450 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
11460 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
11470 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
11480 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
11490 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
114a0 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
114b0 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
114c0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
114d0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
114e0 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
114f0 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
11500 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
11510 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
11520 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
11530 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
11540 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
11550 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
11560 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
11570 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
11580 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
11590 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
115a0 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
115b0 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
115c0 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
115d0 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
115e0 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
115f0 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
11600 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
11610 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
11620 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
11630 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
11640 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
11650 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
11660 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
11670 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
11680 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
11690 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
116a0 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
116b0 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
116c0 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
116d0 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
116e0 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
116f0 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
11700 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
11710 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
11720 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
11730 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
11740 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
11750 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
11760 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
11770 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
11780 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
11790 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
117a0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
117b0 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
117c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
117d0 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
117e0 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
117f0 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
11800 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
11810 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
11820 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
11830 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
11840 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
11850 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
11860 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
11870 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
11880 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
11890 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
118a0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
118b0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
118c0 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
118d0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
118e0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
118f0 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
11900 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
11910 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
11920 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
11930 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
11940 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
11950 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
11960 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
11970 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
11980 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11990 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
119a0 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
119b0 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
119c0 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
119d0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
119e0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
119f0 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
11a00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11a10 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
11a20 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
11a30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
11a40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
11a50 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
11a60 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
11a70 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11a80 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
11a90 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
11aa0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
11ab0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
11ac0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11ad0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
11ae0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
11af0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
11b00 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
11b10 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
11b20 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
11b30 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
11b40 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
11b50 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
11b60 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
11b70 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
11b80 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
11b90 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
11ba0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
11bb0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
11bc0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11bd0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
11be0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
11bf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
11c00 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
11c10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11c20 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
11c30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
11c40 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
11c50 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
11c60 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
11c70 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
11c80 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
11c90 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
11ca0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
11cb0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
11cc0 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
11cd0 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
11ce0 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
11cf0 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
11d00 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
11d10 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
11d20 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11d30 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11d40 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11d50 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11d60 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11d70 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11d80 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
11d90 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
11da0 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
11db0 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
11dc0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
11dd0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
11de0 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
11df0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
11e00 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
11e10 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
11e20 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
11e30 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11e40 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
11e50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
11e60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11e70 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11e80 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11e90 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11ea0 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
11eb0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
11ec0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
11ed0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
11ee0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
11ef0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
11f00 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
11f10 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
11f20 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
11f30 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
11f40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11f50 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
11f60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11f70 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
11f80 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
11f90 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
11fa0 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
11fb0 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
11fc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
11fd0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
11fe0 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
11ff0 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
12000 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
12010 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
12020 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
12030 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
12040 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
12050 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
12060 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
12070 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
12080 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
12090 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
120a0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
120b0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
120c0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
120d0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
120e0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
120f0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
12100 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12110 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12120 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
12130 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
12140 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
12150 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
12160 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12170 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
12180 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
12190 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
121a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
121b0 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
121c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
121d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
121e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
121f0 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
12200 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
12210 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
12220 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
12230 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12240 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
12250 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
12260 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
12270 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
12280 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
12290 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
122a0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
122b0 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
122c0 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
122d0 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
122e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
122f0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12300 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
12310 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
12320 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
12330 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
12340 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12350 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
12360 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
12370 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
12380 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
12390 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
123a0 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
123b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
123c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
123d0 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
123e0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
123f0 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
12400 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
12410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12420 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
12430 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12440 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
12450 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
12460 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
12470 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12480 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
12490 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
124a0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
124b0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
124c0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
124d0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
124e0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
124f0 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
12500 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12510 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
12520 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12530 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12540 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
12550 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
12560 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
12570 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
12580 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
12590 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
125a0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
125b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
125c0 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
125d0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
125e0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
125f0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12600 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12610 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
12620 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
12630 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12640 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12650 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
12660 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
12670 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
12680 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
12690 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
126a0 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
126b0 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
126c0 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
126d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
126e0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
126f0 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65  QLite.)^ ^SQLite
12700 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77   makes.** its ow
12710 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
12720 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  f the content of
12730 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12740 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12750 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ture.** before t
12760 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
12770 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  ig()] call retur
12780 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
12790 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
127a0 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  ETMALLOC]] <dt>S
127b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
127c0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
127d0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
127e0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
127f0 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
12800 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12810 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
12820 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
12830 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12840 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12850 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
12860 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
12870 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
12880 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
12890 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
128a0 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
128b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
128c0 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
128d0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
128e0 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
128f0 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
12900 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
12910 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
12920 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
12930 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
12940 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
12950 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
12960 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
12970 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
12980 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12990 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
129a0 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
129b0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
129c0 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
129d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
129e0 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69  G_MEMSTATUS opti
129f0 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
12a00 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
12a10 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72   int,.** interpr
12a20 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
12a30 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
12a40 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
12a50 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a   collection of.*
12a60 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
12a70 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20  ion statistics. 
12a80 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
12a90 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12aa0 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  ics are.** disab
12ab0 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  led, the followi
12ac0 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
12ad0 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
12ae0 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
12af0 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
12b00 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
12b10 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
12b20 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
12b30 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
12b40 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12b50 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
12b60 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
12b70 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
12b80 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  s64()].**   </ul
12b90 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
12ba0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12bb0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
12bc0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
12bd0 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
12be0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
12bf0 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
12c00 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
12c10 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
12c20 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
12c30 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
12c40 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
12c50 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
12c60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12c70 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
12c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12c90 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
12ca0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
12cb0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74  NFIG_SCRATCH opt
12cc0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
12cd0 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12ce0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ffer.** that SQL
12cf0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
12d00 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
12d10 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72   ^(There are thr
12d20 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  ee arguments.** 
12d30 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
12d40 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69  _SCRATCH:  A poi
12d50 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
12d60 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
12d70 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
12d80 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
12d90 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
12da0 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
12db0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
12dc0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
12dd0 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
12de0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
12df0 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
12e00 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a  cations (N).)^.*
12e10 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
12e20 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
12e30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
12e40 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
12e50 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
12e60 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
12e70 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
12e80 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20  te will not use 
12e90 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
12ea0 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
12eb0 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51  r thread..** ^SQ
12ec0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
12ed0 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63  request a scratc
12ee0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
12ef0 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
12f00 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
12f10 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a  se page size..**
12f20 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
12f30 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
12f40 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
12f50 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
12f60 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
12f70 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
12f80 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
12f90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
12fa0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
12fb0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
12fc0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
12fd0 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  <p>.** ^When the
12fe0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f   application pro
12ff0 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74  vides any amount
13000 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f   of scratch memo
13010 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49  ry using.** SQLI
13020 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13030 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73  H, SQLite avoids
13040 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72   unnecessary lar
13050 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  ge.** [sqlite3_m
13060 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63  alloc|heap alloc
13070 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73  ations]..** This
13080 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f   can help [Robso
13090 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20  n proof|prevent 
130a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
130b0 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20  n failures] due 
130c0 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d  to heap.** fragm
130d0 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d  entation in low-
130e0 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20  memory embedded 
130f0 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64  systems..** </dd
13100 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13110 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13120 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
13130 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
13140 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13160 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
13170 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13180 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
13190 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
131a0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
131b0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
131c0 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
131d0 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
131e0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
131f0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
13200 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
13210 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
13220 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
13230 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
13240 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
13250 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
13260 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
13270 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
13280 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
13290 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68  n option..** ^Th
132a0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
132b0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
132c0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
132d0 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
132e0 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
132f0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
13300 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
13310 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
13320 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
13330 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
13340 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
13350 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
13360 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
13370 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
13380 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
13390 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
133a0 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
133b0 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
133c0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
133d0 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
133e0 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
133f0 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
13400 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
13410 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
13420 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
13430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13440 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69  ACHE_HDRSZ] opti
13450 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  on .** to [sqlit
13460 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
13470 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
13480 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
13490 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
134a0 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61  ** for the sz pa
134b0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61  rameter to be la
134c0 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73  rger than necess
134d0 61 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a  ary.  The first.
134e0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
134f0 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ld pointer to an
13500 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13510 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
13520 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65  that.** is at le
13530 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
13540 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77  f memory, otherw
13550 69 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62  ise subsequent b
13560 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
13570 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c  defined..** ^SQL
13580 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
13590 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
135a0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
135b0 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
135c0 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
135d0 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
135e0 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
135f0 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
13600 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
13610 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
13620 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
13630 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
13640 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
13650 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
13660 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
13670 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13680 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
13690 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
136a0 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  pace.</dd>.**.**
136b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
136c0 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
136d0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
136e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
136f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
13700 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
13710 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13720 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
13730 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
13740 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
13750 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
13760 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
13770 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
13780 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
13790 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
137a0 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a  IG_SCRATCH] and.
137b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
137c0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
137d0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
137e0 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
137f0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
13800 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
13810 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
13820 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
13830 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
13840 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
13850 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
13860 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
13870 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
13880 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
13890 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
138a0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
138b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
138c0 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
138d0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
138e0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
138f0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
13900 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
13910 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
13920 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
13930 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
13940 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
13950 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
13960 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
13970 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
13980 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
13990 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
139a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
139b0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
139c0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
139d0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
139e0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
139f0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
13a00 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13a10 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
13a20 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
13a30 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
13a40 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
13a50 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
13a60 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
13a70 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
13a80 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
13a90 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
13aa0 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
13ab0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
13ac0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
13ad0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
13ae0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
13af0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
13b00 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
13b10 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
13b20 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
13b30 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
13b40 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
13b50 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
13b60 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
13b70 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
13b80 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
13b90 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
13ba0 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
13bb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13bc0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
13bd0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
13be0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13bf0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13c00 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
13c10 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13c20 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
13c30 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
13c40 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13c50 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
13c60 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13c70 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
13c80 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
13c90 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
13ca0 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
13cb0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
13cc0 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
13cd0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
13ce0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
13cf0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
13d00 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
13d10 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
13d20 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
13d30 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13d40 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
13d50 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
13d60 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
13d70 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
13d80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13d90 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13da0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13db0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13dc0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13dd0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
13de0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
13df0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
13e00 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
13e10 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
13e20 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
13e30 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13e40 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
13e50 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
13e60 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13e70 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13e80 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
13e90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13ea0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13eb0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
13ec0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13ed0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
13ee0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
13ef0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
13f00 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13f10 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13f20 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
13f30 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13f40 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13f50 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
13f60 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
13f70 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
13f80 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
13f90 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
13fa0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
13fb0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
13fc0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
13fd0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13fe0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13ff0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
14000 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
14010 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
14020 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
14030 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
14040 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
14050 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
14060 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
14070 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
14080 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14090 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
140a0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
140b0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
140c0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
140d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
140e0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
140f0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
14100 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
14110 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
14120 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
14130 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14140 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
14150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14160 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
14170 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
14180 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
14190 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
141a0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
141b0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
141c0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
141d0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
141e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
141f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14200 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
14210 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
14220 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
14230 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
14240 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
14250 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
14260 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
14270 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
14280 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14290 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
142a0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
142b0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
142c0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
142d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
142e0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
142f0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
14300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
14310 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
14320 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
14330 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
14340 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
14350 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
14360 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
14370 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
14380 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
14390 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
143a0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
143b0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
143c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
143d0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
143e0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
143f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14400 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
14410 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14420 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
14430 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14450 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
14460 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14470 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
14480 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14490 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
144a0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
144b0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
144c0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
144d0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
144e0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
144f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14500 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
14510 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
14520 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
14530 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14540 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
14550 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14560 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
14570 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14580 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
14590 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
145a0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
145b0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
145c0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
145d0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
145e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
145f0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14600 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14610 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
14620 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
14630 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
14640 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
14650 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
14660 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14680 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
14690 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
146a0 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
146b0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
146c0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
146d0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
146e0 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
146f0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
14700 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14710 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
14720 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14730 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
14740 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
14750 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
14760 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
14770 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
14780 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
14790 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
147a0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
147b0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
147c0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
147d0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
147e0 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
147f0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
14800 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
14810 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
14820 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
14830 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
14840 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
14850 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
14860 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
14870 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
14880 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14890 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
148a0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
148b0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
148c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
148d0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
148e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
148f0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
14900 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
14910 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
14920 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
14930 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
14940 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
14950 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
14960 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
14970 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
14980 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
14990 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
149a0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
149b0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
149c0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
149d0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
149e0 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
149f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
14a00 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
14a10 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
14a20 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
14a30 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
14a40 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
14a50 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
14a60 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
14a70 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
14a80 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
14a90 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
14aa0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
14ab0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
14ac0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
14ad0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
14ae0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
14af0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
14b00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
14b10 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
14b20 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
14b30 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
14b40 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14b50 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
14b60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14b70 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
14b80 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14b90 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
14ba0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14bb0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
14bc0 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
14bd0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
14be0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
14bf0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
14c00 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
14c10 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
14c20 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
14c30 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
14c40 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
14c50 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
14c60 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
14c70 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
14c80 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
14c90 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
14ca0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
14cb0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
14cc0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
14cd0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
14ce0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
14cf0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
14d00 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
14d10 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
14d20 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
14d30 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
14d40 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
14d50 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
14d60 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
14d70 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
14d80 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
14d90 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
14da0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
14db0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
14dc0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
14dd0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
14de0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
14df0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
14e00 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
14e10 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
14e20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
14e30 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
14e40 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
14e50 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
14e60 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
14e70 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
14e80 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
14e90 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
14ea0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14eb0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
14ec0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14ed0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
14ee0 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
14ef0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14f00 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14f10 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
14f20 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
14f30 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
14f40 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
14f50 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
14f60 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
14f70 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
14f80 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
14f90 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
14fa0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
14fb0 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
14fc0 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
14fd0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
14fe0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
14ff0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
15000 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
15010 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
15020 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15030 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
15040 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
15050 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
15060 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
15070 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
15080 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
15090 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
150a0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
150b0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
150c0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
150d0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
150e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
150f0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
15100 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
15110 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
15120 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
15130 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
15140 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
15150 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
15160 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
15170 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
15180 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
15190 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
151a0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
151b0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
151c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
151d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
151e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
151f0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
15200 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15210 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
15220 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15230 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
15240 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
15250 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
15260 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
15270 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
15280 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
15290 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
152a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
152b0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
152c0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
152d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
152e0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
152f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
15300 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
15310 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
15320 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
15330 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15340 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
15350 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
15360 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
15370 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
15380 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15390 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
153a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
153b0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
153c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
153d0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
153e0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
153f0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
15400 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
15410 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
15420 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
15430 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
15440 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
15450 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
15460 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
15470 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
15480 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
15490 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
154a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
154b0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
154c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
154d0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
154e0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
154f0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
15500 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
15510 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
15520 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
15530 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
15540 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
15550 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
15560 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
15570 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
15580 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
15590 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
155a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
155b0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
155c0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
155d0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
155e0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
155f0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
15600 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
15610 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
15620 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
15630 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
15640 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
15650 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
15660 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
15670 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
15680 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
15690 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
156a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
156b0 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
156c0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
156d0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
156e0 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
156f0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
15700 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
15710 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15720 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
15730 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15740 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
15750 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
15760 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
15770 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
15780 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
15790 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
157a0 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
157b0 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
157c0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
157d0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
157e0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
157f0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
15800 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15810 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
15820 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
15830 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
15840 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
15850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15860 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
15870 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
15880 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
15890 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
158a0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
158b0 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
158c0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
158d0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
158e0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
158f0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
15900 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
15910 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
15920 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
15930 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
15940 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
15950 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
15960 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
15970 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
15980 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15990 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
159a0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
159b0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
159c0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
159d0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
159e0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
159f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
15a00 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
15a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15a20 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
15a30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15a40 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15a50 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
15a60 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15a70 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
15a80 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
15a90 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
15aa0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
15ab0 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
15ac0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
15ad0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
15ae0 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
15af0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
15b00 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15b10 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
15b20 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
15b30 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
15b40 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
15b50 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
15b60 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
15b70 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
15b80 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
15b90 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
15ba0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15bb0 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
15bc0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
15bd0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
15be0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15bf0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
15c00 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
15c10 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
15c20 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
15c30 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
15c40 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
15c50 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
15c60 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
15c70 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
15c80 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
15c90 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
15ca0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
15cb0 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
15cc0 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
15cd0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
15ce0 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
15cf0 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
15d00 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
15d10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15d20 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
15d30 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15d40 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
15d50 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
15d60 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
15d70 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15d80 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
15d90 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
15da0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
15db0 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
15dc0 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
15dd0 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
15de0 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
15df0 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
15e00 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
15e10 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
15e20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
15e30 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
15e40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15e50 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
15e60 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
15e70 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
15e80 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
15e90 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
15ea0 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
15eb0 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
15ec0 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
15ed0 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
15ee0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
15ef0 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
15f00 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
15f10 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
15f20 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
15f30 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
15f40 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
15f50 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
15f60 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  lue..** </dl>.*/
15f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15f80 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
15f90 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
15fa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15fb0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
15fc0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
15fd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15fe0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
15ff0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
16000 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16010 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
16020 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
16030 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16040 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16060 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
16070 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
16080 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16090 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
160a0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
160b0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
160c0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
160d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
160e0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
160f0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
16100 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
16110 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16120 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
16130 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
16140 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
16150 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16160 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
16170 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
16180 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
16190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
161a0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
161b0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
161c0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
161d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
161e0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
161f0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
16200 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
16210 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
16220 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
16230 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
16240 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
16250 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
16260 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
16270 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
16280 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
162a0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
162b0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
162c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
162d0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
162e0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
162f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16300 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
16310 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
16320 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16340 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
16350 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
16360 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16370 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
16380 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
16390 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
163a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
163b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
163c0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
163d0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
163e0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
163f0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
16400 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
16410 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
16420 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16430 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
16440 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
16450 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
16460 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16470 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
16480 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
16490 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
164a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
164b0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
164c0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
164d0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
164e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
164f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
16500 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
16510 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
16520 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16530 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
16540 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
16550 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
16560 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a */../*.** CAPI
16570 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
16580 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
16590 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
165a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
165b0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
165c0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
165d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
165e0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
165f0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
16600 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16610 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
16620 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16630 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
16640 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
16650 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
16660 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
16670 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
16680 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
16690 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
166a0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
166b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
166c0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
166d0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
166e0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
166f0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
16700 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
16710 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
16720 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
16730 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
16740 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
16750 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
16760 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
16770 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
16780 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
16790 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
167a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
167b0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
167c0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
167d0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
167e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
167f0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16800 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
16810 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
16820 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
16830 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
16840 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
16850 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
16860 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
16870 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16880 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
16890 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
168a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
168b0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
168c0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
168d0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
168e0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
168f0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
16900 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
16910 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
16920 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
16930 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16940 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
16950 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
16960 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
16970 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
16980 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
16990 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
169a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
169b0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
169c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
169d0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
169e0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
169f0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
16a00 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
16a10 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
16a20 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
16a30 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
16a40 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
16a50 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
16a60 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
16a70 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
16a80 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
16a90 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
16aa0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
16ab0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
16ac0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
16ad0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
16ae0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
16af0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
16b00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16b10 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
16b20 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
16b30 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
16b40 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
16b50 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
16b60 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
16b70 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
16b80 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
16b90 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
16ba0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
16bb0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
16bc0 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
16bd0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
16be0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
16bf0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
16c00 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
16c10 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
16c20 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
16c30 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
16c40 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
16c50 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
16c60 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
16c70 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
16c80 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
16c90 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
16ca0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
16cb0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
16cc0 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
16cd0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
16ce0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
16cf0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
16d00 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
16d10 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
16d20 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
16d30 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
16d40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
16d50 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
16d60 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16d70 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
16d80 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
16d90 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
16da0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
16db0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
16dc0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
16dd0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
16de0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
16df0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16e00 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
16e10 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
16e20 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
16e30 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
16e40 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
16e50 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
16e60 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
16e70 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
16e80 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
16e90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16ea0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
16eb0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
16ec0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
16ed0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
16ee0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
16ef0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16f00 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
16f10 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
16f20 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
16f30 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
16f40 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
16f50 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
16f60 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
16f70 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
16f80 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
16f90 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
16fa0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
16fb0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
16fc0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
16fd0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
16fe0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
16ff0 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
17000 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17010 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
17020 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
17030 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17040 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
17050 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
17060 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
17070 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
17080 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
17090 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
170a0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
170b0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
170c0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
170d0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
170e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
170f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17100 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17110 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
17120 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17130 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
17140 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
17150 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
17160 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
17170 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
17180 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
17190 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
171a0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
171b0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
171c0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
171d0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
171e0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
171f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17200 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17210 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
17220 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
17230 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17240 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17250 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
17260 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
17270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
17280 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
17290 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
172a0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
172b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
172c0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
172d0 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
172e0 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
172f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
17300 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
17310 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
17320 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
17330 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
17340 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
17350 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
17360 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
17370 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
17380 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
17390 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
173a0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
173b0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
173c0 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
173d0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
173e0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
173f0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
17400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17410 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
17420 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
17430 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
17440 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
17450 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
17460 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
17470 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
17480 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
17490 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
174a0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
174b0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
174c0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
174d0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
174e0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
174f0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
17500 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
17510 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
17520 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
17530 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
17540 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
17550 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
17560 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
17570 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
17580 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
17590 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
175a0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
175b0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
175c0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
175d0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
175e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
175f0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17600 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
17610 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
17620 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
17630 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
17640 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17650 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
17660 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
17670 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
17680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17690 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
176a0 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
176b0 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
176c0 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
176d0 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
176e0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
176f0 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
17700 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
17710 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
17720 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17730 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
17740 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17750 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
17760 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
17770 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
17780 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
17790 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
177a0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
177b0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
177c0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
177d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
177e0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
177f0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
17800 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
17810 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17820 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
17830 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
17840 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
17850 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
17860 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
17870 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17880 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
17890 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
178a0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
178b0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
178c0 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
178d0 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
178e0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
178f0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
17900 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
17910 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
17920 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
17930 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17940 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
17950 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
17960 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
17970 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
17980 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
17990 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
179a0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
179b0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
179c0 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
179d0 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
179e0 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
179f0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
17a00 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
17a10 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
17a20 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
17a30 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
17a40 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
17a50 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17a60 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
17a70 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
17a80 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
17a90 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
17aa0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
17ab0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
17ac0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
17ad0 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
17ae0 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
17af0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
17b00 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
17b10 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
17b20 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
17b30 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
17b40 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
17b50 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
17b60 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
17b70 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
17b80 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
17b90 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
17ba0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
17bb0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
17bc0 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
17bd0 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
17be0 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
17bf0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
17c00 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17c10 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17c20 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
17c30 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
17c40 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
17c50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
17c60 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
17c70 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17c80 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
17c90 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
17ca0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
17cb0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
17cc0 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
17cd0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17ce0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
17cf0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17d00 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
17d10 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
17d20 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
17d30 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
17d40 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
17d50 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
17d60 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
17d70 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17d80 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
17d90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17da0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
17db0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
17dc0 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
17dd0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
17de0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
17df0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
17e00 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
17e10 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
17e20 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
17e30 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
17e40 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
17e50 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
17e60 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
17e70 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
17e80 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
17e90 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
17ea0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
17eb0 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
17ec0 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
17ed0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
17ee0 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
17ef0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
17f00 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
17f10 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
17f20 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
17f30 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
17f40 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
17f50 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
17f60 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
17f70 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
17f80 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
17f90 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
17fa0 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
17fb0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
17fc0 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
17fd0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
17fe0 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
17ff0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
18000 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
18010 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
18020 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
18030 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
18040 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
18050 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
18060 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
18070 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
18080 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
18090 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
180a0 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
180b0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
180c0 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
180d0 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
180e0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
180f0 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
18100 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
18110 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
18120 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
18130 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
18140 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
18150 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
18160 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
18170 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
18180 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
18190 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
181a0 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
181b0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
181c0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
181d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
181e0 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
181f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
18200 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
18210 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
18220 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
18230 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
18240 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
18250 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
18260 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
18270 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18280 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
18290 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
182a0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
182b0 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
182c0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
182d0 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
182e0 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
182f0 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
18300 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
18310 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
18320 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
18330 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
18340 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
18350 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
18360 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
18370 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
18380 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
18390 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
183a0 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
183b0 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
183c0 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
183d0 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
183e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
183f0 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
18400 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
18410 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
18420 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
18430 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
18440 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
18450 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
18460 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
18470 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
18480 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
18490 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
184a0 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
184b0 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
184c0 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
184d0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
184e0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
184f0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
18500 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
18510 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
18520 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
18530 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
18540 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
18550 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
18560 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
18570 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
18580 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
18590 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
185a0 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
185b0 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
185c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
185d0 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
185e0 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
185f0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
18600 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
18610 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
18620 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
18630 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
18640 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
18650 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
18660 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
18670 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
18680 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
18690 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
186a0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
186b0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
186c0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
186d0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
186e0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
186f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18700 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
18710 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
18720 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
18730 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18740 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
18750 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
18760 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
18770 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
18780 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
18790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
187a0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
187b0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
187c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
187d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
187e0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
187f0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
18800 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
18810 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
18820 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
18830 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
18840 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
18850 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
18860 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
18870 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18880 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
18890 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
188a0 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
188b0 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
188c0 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
188d0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
188e0 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
188f0 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
18900 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
18910 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
18920 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18930 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
18940 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
18950 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
18960 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
18970 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
18980 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
18990 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
189a0 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
189b0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
189c0 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
189d0 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
189e0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
189f0 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
18a00 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
18a10 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
18a20 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
18a30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
18a40 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
18a50 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
18a60 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
18a70 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
18a80 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
18a90 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
18aa0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
18ab0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
18ac0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
18ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18ae0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
18af0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18b00 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
18b10 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
18b20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
18b30 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
18b40 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
18b50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18b60 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
18b70 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18b80 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
18b90 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
18ba0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
18bb0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
18bc0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
18bd0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
18be0 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
18bf0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
18c00 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
18c10 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
18c20 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
18c30 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
18c40 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
18c50 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
18c60 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
18c70 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
18c80 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
18c90 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
18ca0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
18cb0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
18cc0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
18cd0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
18ce0 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
18cf0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
18d00 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
18d10 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
18d20 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
18d30 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
18d40 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
18d50 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
18d60 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
18d70 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
18d80 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
18d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18da0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
18db0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
18dc0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
18dd0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18de0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
18df0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
18e00 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
18e10 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
18e20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
18e30 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18e40 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
18e50 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
18e60 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
18e70 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
18e80 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
18e90 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
18ea0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
18eb0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
18ec0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
18ed0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
18ee0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
18ef0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
18f00 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
18f10 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
18f20 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
18f30 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
18f40 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
18f50 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
18f60 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
18f70 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
18f80 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
18f90 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
18fa0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
18fb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
18fc0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
18fd0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
18fe0 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
18ff0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
19000 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
19010 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19020 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
19030 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
19040 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
19050 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
19060 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
19070 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
19080 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
19090 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
190a0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
190b0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
190c0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
190d0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
190e0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
190f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19100 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
19110 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
19120 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
19130 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
19140 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
19150 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
19160 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
19170 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
19180 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
19190 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
191a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
191b0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
191c0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
191d0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
191e0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
191f0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
19200 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
19210 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
19220 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
19230 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
19240 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
19250 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
19260 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
19270 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
19280 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
19290 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
192a0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
192b0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
192c0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
192d0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
192e0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
192f0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
19300 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
19310 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
19320 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
19330 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
19340 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
19350 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
19360 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
19370 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
19380 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
19390 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
193a0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
193b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
193c0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
193d0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
193e0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
193f0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
19400 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
19410 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
19420 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
19430 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
19440 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
19450 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
19460 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
19470 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
19480 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
19490 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
194a0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
194b0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
194c0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
194d0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
194e0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
194f0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
19500 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
19510 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
19520 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
19530 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
19540 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
19550 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
19560 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
19570 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
19580 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
19590 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
195a0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
195b0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
195c0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
195d0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
195e0 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
195f0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
19600 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
19610 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
19620 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
19630 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
19640 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
19650 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
19660 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
19670 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
19680 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
19690 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
196a0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
196b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
196c0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
196d0 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
196e0 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
196f0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
19700 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
19710 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
19720 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
19730 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
19740 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
19750 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
19760 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
19770 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
19780 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
19790 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
197a0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
197b0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
197c0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
197d0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
197e0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
197f0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
19800 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
19810 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
19820 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19830 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
19840 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
19850 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
19860 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
19870 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
19880 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
19890 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
198a0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
198b0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
198c0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
198d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
198e0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
198f0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
19900 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
19910 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
19920 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
19930 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
19940 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
19950 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
19960 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
19970 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
19980 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
19990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
199a0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
199b0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
199c0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
199d0 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
199e0 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
199f0 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
19a00 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
19a10 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19a20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
19a30 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
19a40 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
19a50 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19a60 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
19a70 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
19a80 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
19a90 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
19aa0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
19ab0 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
19ac0 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
19ad0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
19ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19af0 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
19b00 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
19b10 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
19b20 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
19b30 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
19b40 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
19b50 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
19b60 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
19b70 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19b80 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
19b90 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
19ba0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
19bb0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
19bc0 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
19bd0 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
19be0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
19bf0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
19c00 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
19c10 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
19c20 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
19c30 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
19c40 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
19c50 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
19c60 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
19c70 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
19c80 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
19c90 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
19ca0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
19cb0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
19cc0 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
19cd0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
19ce0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19cf0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
19d00 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
19d10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19d20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
19d30 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
19d40 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
19d50 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
19d60 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
19d70 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
19d80 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
19d90 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
19da0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
19db0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
19dc0 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
19dd0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
19de0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
19df0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
19e00 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
19e10 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
19e20 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
19e30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
19e40 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
19e50 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
19e60 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
19e70 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
19e80 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
19e90 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
19ea0 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
19eb0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
19ec0 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
19ed0 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
19ee0 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
19ef0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
19f00 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
19f10 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
19f20 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
19f30 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
19f40 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
19f50 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
19f60 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
19f70 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
19f80 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
19f90 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
19fa0 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
19fb0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
19fc0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
19fd0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
19fe0 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
19ff0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1a000 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1a010 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1a020 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1a030 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1a040 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1a050 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1a060 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1a070 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1a080 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1a090 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1a0a0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1a0b0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1a0c0 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1a0d0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1a0e0 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1a0f0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1a100 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1a110 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1a120 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1a130 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1a140 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1a150 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1a160 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1a170 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1a180 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1a190 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1a1a0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1a1b0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1a1c0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1a1d0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1a1e0 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1a1f0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1a200 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1a210 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1a220 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1a230 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1a240 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1a250 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1a260 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1a270 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1a280 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1a290 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1a2a0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1a2b0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1a2c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1a2d0 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1a2e0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1a2f0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1a300 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1a310 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1a320 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1a330 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1a340 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1a350 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1a360 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1a370 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1a380 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1a390 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1a3a0 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1a3b0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1a3c0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1a3d0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1a3e0 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1a3f0 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1a400 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a410 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1a420 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1a430 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1a440 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1a450 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1a460 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1a470 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1a480 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1a490 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1a4a0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1a4b0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1a4c0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1a4d0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1a4e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a4f0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1a500 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1a510 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
1a520 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1a530 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
1a540 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
1a550 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1a560 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1a570 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1a580 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1a590 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1a5a0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1a5b0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1a5c0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1a5d0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1a5e0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1a5f0 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1a600 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1a610 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1a620 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1a630 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1a640 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1a650 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1a660 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1a670 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1a680 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1a690 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1a6a0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1a6b0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1a6c0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1a6d0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1a6e0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1a6f0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1a700 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1a710 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1a720 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1a730 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1a740 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1a750 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1a760 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1a770 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1a780 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1a790 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1a7a0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1a7b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1a7c0 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1a7d0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1a7e0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1a7f0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1a800 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1a810 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1a820 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1a830 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1a840 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1a850 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1a860 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1a870 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1a880 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1a890 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ut].*/.int sqlit
1a8a0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1a8b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1a8c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a8d0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1a8e0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1a8f0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1a900 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a910 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1a920 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1a930 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1a940 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1a950 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1a960 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1a970 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1a980 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1a990 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1a9a0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1a9b0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1a9c0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1a9d0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1a9e0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1a9f0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1aa00 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1aa10 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1aa20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1aa30 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1aa40 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1aa50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1aa60 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1aa70 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1aa80 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1aa90 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1aaa0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1aab0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1aac0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1aad0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1aae0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1aaf0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1ab00 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1ab10 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1ab20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1ab30 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1ab40 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1ab50 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1ab60 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1ab70 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1ab80 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1ab90 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1aba0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1abb0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1abc0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1abd0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1abe0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1abf0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1ac00 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1ac10 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1ac20 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1ac30 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1ac40 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1ac50 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1ac60 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1ac70 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1ac80 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1ac90 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1aca0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1acb0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1acc0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1acd0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1ace0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1acf0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1ad00 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1ad10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1ad20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1ad30 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1ad40 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1ad50 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1ad60 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1ad70 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1ad80 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1ad90 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1ada0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1adb0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1adc0 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1add0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1ade0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1adf0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1ae00 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1ae10 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1ae20 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1ae30 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1ae40 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1ae50 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1ae60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1ae70 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1ae80 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1ae90 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1aea0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1aeb0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1aec0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1aed0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1aee0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1aef0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1af00 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1af10 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1af20 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1af30 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1af40 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1af50 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1af60 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1af70 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1af80 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1af90 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1afa0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1afb0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1afc0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1afd0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1afe0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1aff0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1b000 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b010 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1b020 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b030 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1b040 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1b050 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1b060 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1b070 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1b080 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1b090 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b0a0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1b0b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b0c0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1b0d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b0e0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1b0f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1b100 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1b110 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1b120 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1b130 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1b140 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1b150 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1b160 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1b170 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1b180 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1b190 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1b1a0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1b1b0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1b1c0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1b1d0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1b1e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1b1f0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1b200 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1b210 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b220 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1b230 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1b240 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1b250 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1b260 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1b270 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1b280 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1b290 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1b2a0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1b2b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1b2c0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1b2d0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1b2e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1b2f0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1b300 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1b310 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1b320 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1b330 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1b340 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1b350 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1b360 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1b370 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1b380 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1b390 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1b3a0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1b3b0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1b3c0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1b3d0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1b3e0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1b3f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b400 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1b410 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1b420 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1b430 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1b440 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1b450 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1b460 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1b470 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1b480 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1b490 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1b4a0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1b4b0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1b4c0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1b4d0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1b4e0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1b4f0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1b500 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1b510 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1b520 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1b530 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1b540 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1b550 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1b560 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1b570 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1b580 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1b590 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1b5a0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1b5b0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1b5c0 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1b5d0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1b5e0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1b5f0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1b600 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1b610 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1b620 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1b630 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1b640 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1b650 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1b660 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1b670 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1b680 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1b690 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1b6a0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1b6b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1b6c0 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1b6d0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1b6e0 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1b6f0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1b700 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1b710 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1b720 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1b730 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1b740 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1b750 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1b760 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1b770 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
1b780 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
1b790 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
1b7a0 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72  e common K&R for
1b7b0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c  matting options,
1b7c0 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64  .** plus some ad
1b7d0 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61  ditional non-sta
1b7e0 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64  ndard formats, d
1b7f0 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a  etailed below..*
1b800 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65  * Note that some
1b810 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73   of the more obs
1b820 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20  cure formatting 
1b830 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63  options from rec
1b840 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79  ent.** C-library
1b850 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f   standards are o
1b860 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73  mitted from this
1b870 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1b880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b890 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1b8a0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1b8b0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1b8c0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1b8d0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1b8e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1b8f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b900 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1b910 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1b920 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1b930 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1b940 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1b950 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1b960 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1b970 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1b980 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1b990 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1b9a0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1b9b0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1b9c0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1b9d0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1b9e0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1b9f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1ba00 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1ba10 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1ba20 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1ba30 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1ba40 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1ba50 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1ba60 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1ba70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1ba80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1ba90 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1baa0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1bab0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1bac0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1bad0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1bae0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1baf0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1bb00 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1bb10 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1bb20 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1bb30 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1bb40 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1bb50 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1bb60 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1bb70 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1bb80 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1bb90 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1bba0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1bbb0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1bbc0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1bbd0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1bbe0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1bbf0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1bc00 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1bc10 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1bc20 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1bc30 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1bc40 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1bc50 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1bc60 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1bc70 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1bc80 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1bc90 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1bca0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1bcb0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1bcc0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1bcd0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1bce0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1bcf0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1bd00 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1bd10 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1bd20 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1bd30 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1bd40 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1bd50 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1bd60 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1bd70 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1bd80 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1bd90 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1bda0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1bdb0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1bdc0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1bdd0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1bde0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1bdf0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1be00 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1be10 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1be20 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1be30 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1be40 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1be50 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1be60 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1be70 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1be80 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1be90 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1bea0 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1beb0 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1bec0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1bed0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1bee0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1bef0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1bf00 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1bf10 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1bf20 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1bf30 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20  , "%w" and "%z" 
1bf40 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1bf50 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1bf60 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1bf70 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1bf80 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1bf90 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1bfa0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1bfb0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1bfc0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1bfd0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1bfe0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1bff0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1c000 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1c010 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1c020 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1c030 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1c040 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1c050 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1c060 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1c070 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1c080 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1c090 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1c0a0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1c0b0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1c0c0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1c0d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1c0e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c0f0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1c100 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1c110 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1c120 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c130 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1c140 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1c150 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1c160 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c170 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c180 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1c190 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1c1a0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1c1b0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1c1c0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1c1d0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1c1e0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1c1f0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1c200 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1c210 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c220 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1c230 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1c240 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1c250 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1c260 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1c270 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1c280 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1c290 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c2a0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c2b0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1c2c0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1c2d0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1c2e0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1c2f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c300 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1c310 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1c320 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1c330 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1c340 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1c350 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1c360 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1c370 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1c380 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1c390 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1c3a0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1c3b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c3c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1c3d0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1c3e0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1c3f0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1c400 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1c410 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1c420 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1c430 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1c440 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1c450 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1c460 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1c470 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1c480 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1c490 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1c4a0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1c4b0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1c4c0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1c4d0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1c4e0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1c4f0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1c500 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1c510 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1c520 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1c530 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1c540 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1c550 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1c560 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1c570 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1c580 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c590 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1c5a0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1c5b0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1c5c0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1c5d0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1c5e0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1c5f0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1c600 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1c610 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1c620 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c630 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1c640 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1c650 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1c660 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1c670 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1c680 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1c690 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1c6a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1c6b0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66  .** ^(The "%w" f
1c6c0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1c6d0 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78   is like "%q" ex
1c6e0 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70  cept that it exp
1c6f0 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f  ects to.** be co
1c700 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64  ntained within d
1c710 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73  ouble-quotes ins
1c720 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71  tead of single q
1c730 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a  uotes, and it.**
1c740 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75   escapes the dou
1c750 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63  ble-quote charac
1c760 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ter instead of t
1c770 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a  he single-quote.
1c780 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20  ** character.)^ 
1c790 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74   The "%w" format
1c7a0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69  ting option is i
1c7b0 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65  ntended for safe
1c7c0 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  ly inserting.** 
1c7d0 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
1c7e0 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f   names into a co
1c7f0 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74  nstructed SQL st
1c800 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  atement..**.** ^
1c810 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1c820 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1c830 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1c840 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1c850 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1c860 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1c870 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1c880 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1c890 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1c8a0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1c8b0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1c8c0 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
1c8d0 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1c8e0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1c8f0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1c900 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1c910 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1c920 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1c930 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1c940 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1c950 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
1c960 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1c970 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1c980 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1c990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c9a0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1c9b0 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1c9c0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1c9d0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1c9e0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1c9f0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1ca00 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1ca10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1ca20 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1ca30 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1ca40 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1ca50 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1ca60 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1ca70 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1ca80 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1ca90 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1caa0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1cab0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1cac0 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1cad0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1cae0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1caf0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1cb00 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1cb10 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1cb20 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1cb30 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1cb40 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1cb50 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1cb60 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1cb70 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1cb80 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1cb90 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1cba0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1cbb0 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1cbc0 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1cbd0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1cbe0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1cbf0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1cc00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1cc10 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1cc20 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1cc30 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1cc40 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1cc50 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1cc60 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1cc70 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1cc80 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1cc90 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1cca0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1ccb0 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1ccc0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1ccd0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1cce0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1ccf0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1cd00 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1cd10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1cd20 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1cd30 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1cd40 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1cd50 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1cd60 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1cd70 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1cd80 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1cd90 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1cda0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1cdb0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1cdc0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1cdd0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1cde0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1cdf0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1ce00 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1ce10 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1ce20 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1ce30 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1ce40 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1ce50 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1ce60 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1ce70 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1ce80 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1ce90 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1cea0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1ceb0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1cec0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1ced0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1cee0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1cef0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1cf00 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1cf10 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1cf20 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1cf30 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1cf40 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1cf50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1cf60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1cf70 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1cf80 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1cf90 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1cfa0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1cfb0 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1cfc0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1cfd0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1cfe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1cff0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d000 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1d010 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1d020 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1d030 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1d040 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1d050 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1d060 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1d070 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1d080 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1d090 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1d0a0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1d0b0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1d0c0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1d0d0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1d0e0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1d0f0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1d100 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1d110 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1d120 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1d130 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1d140 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1d150 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1d160 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1d170 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1d180 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1d190 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1d1a0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1d1b0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1d1c0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1d1d0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1d1e0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1d1f0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1d200 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1d210 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1d220 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1d230 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1d240 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1d250 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1d260 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1d270 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1d280 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1d290 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1d2a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1d2b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1d2c0 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1d2d0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1d2e0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1d2f0 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1d300 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1d310 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1d320 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1d330 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1d340 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1d350 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1d360 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d370 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1d380 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1d390 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1d3a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1d3b0 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1d3c0 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1d3d0 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1d3e0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1d3f0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1d400 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1d410 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d420 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1d430 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1d440 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1d450 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1d460 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1d470 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1d480 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1d490 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1d4a0 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1d4b0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1d4c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1d4d0 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1d4e0 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1d4f0 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1d500 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1d510 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1d520 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1d530 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1d540 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1d550 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1d560 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1d570 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1d580 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1d590 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1d5a0 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1d5b0 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1d5c0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1d5d0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1d5e0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1d5f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1d600 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1d610 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1d620 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1d630 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1d640 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1d650 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1d660 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1d670 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1d680 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1d690 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1d6a0 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1d6b0 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1d6c0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1d6d0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1d6e0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1d6f0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1d700 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1d710 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1d720 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1d730 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1d740 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1d750 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1d760 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1d770 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1d780 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1d790 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1d7a0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1d7b0 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1d7c0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1d7d0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1d7e0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1d7f0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1d800 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1d810 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1d820 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1d830 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1d840 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1d850 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1d860 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1d870 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1d880 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1d890 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1d8a0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1d8b0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1d8c0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1d8d0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1d8e0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1d8f0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1d900 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1d910 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1d920 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1d930 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1d940 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1d950 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1d960 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1d970 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1d980 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1d990 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1d9a0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1d9b0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1d9c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1d9d0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1d9e0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1d9f0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1da00 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1da10 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1da20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1da30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1da40 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1da50 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1da60 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1da70 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1da80 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1da90 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1daa0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1dab0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1dac0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1dad0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1dae0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1daf0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1db00 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
1db10 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1db20 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
1db30 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
1db40 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
1db50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1db60 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1db70 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1db80 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
1db90 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
1dba0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1dbb0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69  ree(void*);.sqli
1dbc0 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
1dbd0 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
1dbe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dbf0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1dc00 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1dc10 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1dc20 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1dc30 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1dc40 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1dc50 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1dc60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1dc70 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1dc80 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1dc90 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1dca0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1dcb0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1dcc0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1dcd0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1dce0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1dcf0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1dd00 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1dd10 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1dd20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1dd30 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1dd40 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1dd50 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1dd60 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1dd70 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1dd80 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1dd90 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1dda0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1ddb0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ddc0 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1ddd0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1dde0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1ddf0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1de00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1de10 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1de20 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1de30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1de40 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1de50 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1de60 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1de70 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1de80 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1de90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1dea0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1deb0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1dec0 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1ded0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1dee0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1def0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1df00 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1df10 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1df20 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1df30 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1df40 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1df50 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1df60 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1df70 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1df80 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1df90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1dfa0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1dfb0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1dfc0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1dfd0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1dfe0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1dff0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1e000 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1e010 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
1e020 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1e030 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1e040 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
1e050 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1e060 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1e070 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1e080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1e090 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1e0a0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
1e0b0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
1e0c0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
1e0d0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
1e0e0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
1e0f0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
1e100 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
1e110 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
1e120 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
1e130 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
1e140 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
1e150 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
1e160 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
1e170 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
1e180 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
1e190 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
1e1a0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
1e1b0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
1e1c0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
1e1d0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
1e1e0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
1e1f0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
1e200 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
1e210 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
1e220 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
1e230 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1e240 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
1e250 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
1e260 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
1e270 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
1e280 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
1e290 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1e2a0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1e2b0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1e2c0 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1e2d0 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1e2e0 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1e2f0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
1e300 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1e310 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
1e320 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
1e330 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1e340 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
1e350 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
1e360 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
1e370 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1e380 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1e390 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
1e3a0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
1e3b0 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
1e3c0 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
1e3d0 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
1e3e0 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
1e3f0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1e400 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1e410 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1e420 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1e430 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1e440 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1e450 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
1e460 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
1e470 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
1e480 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
1e490 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
1e4a0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
1e4b0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  n Callbacks.** M
1e4c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1e4d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1e4e0 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1e4f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e500 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1e510 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1e520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1e530 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1e540 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1e550 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1e560 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1e570 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1e580 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1e590 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1e5a0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1e5b0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1e5c0 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1e5d0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1e5e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e5f0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1e600 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e610 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1e620 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1e630 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
1e640 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
1e650 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
1e660 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
1e670 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
1e680 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
1e690 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1e6a0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
1e6b0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
1e6c0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
1e6d0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1e6e0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1e6f0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1e700 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
1e710 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
1e720 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
1e730 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
1e740 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
1e750 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
1e760 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
1e770 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
1e780 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
1e790 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
1e7a0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
1e7b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1e7c0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
1e7d0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
1e7e0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
1e7f0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
1e800 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
1e810 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1e820 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
1e830 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
1e840 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
1e850 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
1e860 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1e870 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1e880 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
1e890 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1e8a0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1e8b0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1e8c0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1e8d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1e8e0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
1e8f0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
1e900 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
1e910 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
1e920 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1e930 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1e940 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
1e950 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e960 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1e970 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1e980 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
1e990 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1e9a0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1e9b0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
1e9c0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
1e9d0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
1e9e0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1e9f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1ea00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ea10 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
1ea20 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
1ea30 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1ea40 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1ea50 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1ea60 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1ea70 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1ea80 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1ea90 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1eaa0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1eab0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1eac0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1ead0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1eae0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1eaf0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1eb00 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1eb10 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1eb20 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1eb30 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1eb40 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1eb50 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1eb60 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1eb70 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1eb80 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1eb90 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1eba0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1ebb0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1ebc0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1ebd0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1ebe0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1ebf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ec00 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
1ec10 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
1ec20 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
1ec30 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1ec40 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1ec50 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1ec60 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
1ec70 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
1ec80 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
1ec90 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
1eca0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
1ecb0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
1ecc0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
1ecd0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
1ece0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
1ecf0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
1ed00 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
1ed10 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1ed20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
1ed30 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1ed40 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
1ed50 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1ed60 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
1ed70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
1ed80 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
1ed90 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
1eda0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
1edb0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
1edc0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
1edd0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
1ede0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
1edf0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
1ee00 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1ee10 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
1ee20 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
1ee30 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1ee40 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
1ee50 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1ee60 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
1ee70 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
1ee80 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
1ee90 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
1eea0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
1eeb0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
1eec0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
1eed0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
1eee0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
1eef0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
1ef00 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
1ef10 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
1ef20 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
1ef30 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
1ef40 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
1ef50 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
1ef60 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
1ef70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
1ef80 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
1ef90 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
1efa0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
1efb0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
1efc0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
1efd0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
1efe0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
1eff0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
1f000 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
1f010 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
1f020 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1f030 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
1f040 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
1f050 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
1f060 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1f070 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
1f080 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
1f090 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
1f0a0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
1f0b0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
1f0c0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
1f0d0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
1f0e0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
1f0f0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1f100 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
1f110 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
1f120 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
1f130 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
1f140 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
1f150 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
1f160 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
1f170 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
1f180 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
1f190 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
1f1a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f1b0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
1f1c0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
1f1d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1f1e0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
1f1f0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
1f200 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
1f210 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
1f220 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
1f230 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
1f240 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1f250 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1f260 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
1f270 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f280 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1f290 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1f2a0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1f2b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f2c0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1f2d0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
1f2e0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
1f2f0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1f300 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f310 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1f320 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1f330 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1f340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1f350 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1f360 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1f370 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1f380 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
1f390 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f3a0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
1f3b0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1f3c0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
1f3d0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
1f3e0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
1f3f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f400 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
1f410 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
1f420 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
1f430 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
1f440 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
1f450 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
1f460 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
1f470 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
1f480 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
1f490 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
1f4a0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
1f4b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f4c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
1f4d0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
1f4e0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1f4f0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1f500 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
1f510 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
1f520 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
1f530 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
1f540 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
1f550 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
1f560 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
1f570 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1f580 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
1f590 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
1f5a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f5b0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
1f5c0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
1f5d0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1f5e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1f5f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1f600 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1f610 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1f620 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1f630 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1f640 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1f650 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1f660 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1f670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1f680 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1f690 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1f6a0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1f6b0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1f6c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1f6d0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1f6e0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1f6f0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1f700 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1f710 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1f720 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1f730 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1f740 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1f750 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1f760 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1f770 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1f780 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1f790 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1f7a0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1f7b0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1f7c0 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1f7d0 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1f7e0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e  o used as a [con
1f7f0 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
1f800 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e   mode].** return
1f810 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ed from the [sql
1f820 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
1f830 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
1f840 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
1f850 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
1f860 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
1f870 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
1f880 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
1f890 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
1f8a0 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
1f8b0 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
1f8c0 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
1f8d0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
1f8e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1f8f0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
1f900 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1f910 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1f920 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
1f930 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
1f940 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1f950 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
1f960 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
1f970 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
1f980 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
1f990 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1f9a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1f9b0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1f9c0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
1f9d0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1f9e0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
1f9f0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
1fa00 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
1fa10 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
1fa20 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
1fa30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fa40 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
1fa50 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1fa60 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
1fa70 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
1fa80 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
1fa90 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
1faa0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
1fab0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
1fac0 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
1fad0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
1fae0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1faf0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
1fb00 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
1fb10 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
1fb20 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
1fb30 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
1fb40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1fb50 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
1fb60 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
1fb70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fb80 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
1fb90 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1fba0 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
1fbb0 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
1fbc0 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
1fbd0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
1fbe0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1fbf0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1fc00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1fc10 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
1fc20 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
1fc30 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1fc40 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
1fc50 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
1fc60 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
1fc70 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
1fc80 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
1fc90 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
1fca0 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1fcb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fcc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
1fcd0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
1fce0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
1fcf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fd00 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
1fd10 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
1fd20 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1fd30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1fd40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fd50 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
1fd60 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
1fd70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1fd80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fd90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1fda0 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
1fdb0 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
1fdc0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1fdd0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1fde0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1fdf0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
1fe00 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
1fe10 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1fe20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fe30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1fe40 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
1fe50 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
1fe60 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1fe70 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fe80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fe90 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
1fea0 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
1feb0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1fec0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fed0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1fee0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1fef0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
1ff00 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1ff10 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ff20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ff30 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1ff40 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
1ff50 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ff60 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ff70 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
1ff80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
1ff90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ffa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ffb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ffc0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
1ffd0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
1ffe0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1fff0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
20000 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20010 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
20020 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
20030 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20040 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20050 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20060 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
20070 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
20080 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20090 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
200a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
200b0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
200c0 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
200d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
200e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
200f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20100 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
20110 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
20120 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
20130 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20140 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20150 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
20160 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
20170 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
20180 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20190 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
201a0 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
201b0 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
201c0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
201d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
201e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
201f0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
20200 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
20210 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
20220 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20230 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20240 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
20250 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
20260 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
20270 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
20290 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
202a0 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
202b0 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
202c0 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
202d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
202e0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
202f0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
20300 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
20310 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
20320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
20330 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
20340 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
20350 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
20360 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20370 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
20380 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
20390 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
203a0 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
203b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
203c0 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
203d0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
203e0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
203f0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
20400 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
20410 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
20420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20430 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
20440 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20450 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20460 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
20470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
20480 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
20490 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
204a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
204b0 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
204c0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
204d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
204e0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
204f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20500 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
20510 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
20520 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
20530 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20540 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20550 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
20560 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
20570 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20580 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20590 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
205a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
205b0 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
205c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
205d0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
205e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
205f0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
20600 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
20610 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20620 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
20630 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20640 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
20650 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
20660 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20670 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
20680 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20690 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
206a0 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
206b0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
206c0 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
206d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
206e0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
206f0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
20700 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
20710 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
20720 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
20730 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
20740 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
20750 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
20760 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20770 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
20780 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
20790 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
207a0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e3.**.** These r
207b0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
207c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
207d0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
207e0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
207f0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
20800 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
20810 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
20820 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
20830 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
20840 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
20850 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
20860 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
20870 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
20880 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
20890 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
208a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
208b0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
208c0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
208d0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
208e0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
208f0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
20900 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
20910 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
20920 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
20930 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
20940 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
20950 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
20960 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
20970 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
20980 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
20990 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
209a0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
209b0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
209c0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
209d0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
209e0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
209f0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
20a00 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
20a10 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
20a20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
20a30 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
20a40 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
20a50 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
20a60 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
20a70 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
20a80 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
20a90 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
20aa0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20ab0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
20ac0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
20ad0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
20ae0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
20af0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
20b00 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
20b10 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
20b20 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
20b30 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
20b40 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
20b50 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
20b60 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
20b70 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
20b80 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
20b90 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
20ba0 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
20bb0 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
20bc0 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
20bd0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
20be0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
20bf0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
20c00 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
20c10 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
20c20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
20c30 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
20c40 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
20c50 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
20c60 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
20c70 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
20c80 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
20c90 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
20ca0 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
20cb0 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
20cc0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
20cd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
20ce0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
20cf0 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
20d00 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
20d10 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
20d20 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
20d30 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
20d40 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
20d50 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
20d60 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
20d70 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
20d80 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
20d90 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
20da0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
20db0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
20dc0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
20dd0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
20de0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
20df0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
20e00 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
20e10 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
20e20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
20e30 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
20e40 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
20e50 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
20e60 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
20e70 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
20e80 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
20e90 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
20ea0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
20eb0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
20ec0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
20ed0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
20ee0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
20ef0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
20f00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20f10 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
20f20 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
20f30 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
20f40 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
20f50 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
20f60 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
20f70 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
20f80 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
20f90 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
20fa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20fb0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
20fc0 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
20fd0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
20fe0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
20ff0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
21000 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
21010 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
21020 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
21030 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
21040 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
21050 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
21060 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
21070 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
21080 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
21090 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
210a0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
210b0 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
210c0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
210d0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
210e0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
210f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21100 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
21110 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
21120 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
21130 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
21140 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
21150 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
21160 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
21170 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
21180 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
21190 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
211a0 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
211b0 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
211c0 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
211d0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
211e0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
211f0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
21200 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
21210 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
21220 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
21230 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
21240 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
21250 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
21260 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
21270 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
21280 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
21290 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
212a0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
212b0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
212c0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
212d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
212e0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
212f0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
21300 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
21310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21320 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
21330 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
21340 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
21350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21360 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
21370 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
21380 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
21390 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
213a0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
213b0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
213c0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
213d0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
213e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
213f0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
21400 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
21410 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
21420 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
21430 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
21440 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
21450 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
21460 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
21470 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
21480 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
21490 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
214a0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
214b0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
214c0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
214d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
214e0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
214f0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
21500 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
21510 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
21520 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
21530 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
21540 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
21550 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
21560 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
21570 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
21580 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
21590 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
215a0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
215b0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
215c0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
215d0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
215e0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
215f0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
21600 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
21610 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
21620 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
21630 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
21640 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
21650 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
21660 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
21670 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
21680 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
21690 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
216a0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
216b0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
216c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
216d0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
216e0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
216f0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
21700 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
21710 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
21720 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
21730 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
21740 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
21750 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
21760 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
21770 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
21780 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
21790 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
217a0 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
217b0 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
217c0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
217d0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
217e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
217f0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
21800 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
21810 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
21820 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
21830 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
21840 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
21850 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
21860 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
21870 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
21880 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
21890 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
218a0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
218b0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
218c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
218d0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
218e0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
218f0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
21900 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
21910 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
21920 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
21930 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
21940 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
21950 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
21960 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
21970 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
21980 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
21990 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
219a0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
219b0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
219c0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
219d0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
219e0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
219f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
21a00 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
21a10 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
21a20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
21a30 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
21a40 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
21a50 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
21a60 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
21a70 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
21a80 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
21a90 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
21aa0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
21ab0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
21ac0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
21ad0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
21ae0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
21af0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
21b00 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
21b10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21b20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21b30 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
21b40 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
21b50 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
21b60 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
21b70 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
21b80 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
21b90 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
21ba0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
21bb0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
21bc0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
21bd0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
21be0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
21bf0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
21c00 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
21c10 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
21c20 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
21c30 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
21c40 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
21c50 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
21c60 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
21c70 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
21c80 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
21c90 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
21ca0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
21cb0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
21cc0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
21cd0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
21ce0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21cf0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
21d00 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
21d10 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
21d20 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
21d30 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
21d40 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
21d50 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
21d60 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
21d70 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
21d80 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
21d90 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
21da0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
21db0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
21dc0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
21dd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
21de0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
21df0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
21e00 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
21e10 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
21e20 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
21e30 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
21e40 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
21e50 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
21e60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
21e70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
21e80 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
21e90 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
21ea0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
21eb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
21ec0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
21ed0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
21ee0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
21ef0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
21f00 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
21f10 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
21f20 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
21f30 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
21f40 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
21f50 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
21f60 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
21f70 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
21f80 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
21f90 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
21fa0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
21fb0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
21fc0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
21fd0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
21fe0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
21ff0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
22000 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
22010 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
22020 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
22030 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
22040 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
22050 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
22060 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
22070 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
22080 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
22090 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
220a0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
220b0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
220c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
220d0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
220e0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
220f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
22100 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
22110 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
22120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22130 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
22140 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
22150 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
22160 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
22170 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
22180 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
22190 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
221a0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
221b0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
221c0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
221d0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
221e0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
221f0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
22200 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
22210 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22220 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
22230 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
22240 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
22250 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
22260 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
22270 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
22280 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
22290 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
222a0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
222b0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
222c0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
222d0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
222e0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
222f0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
22300 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
22310 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
22320 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
22330 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22340 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
22350 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
22360 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
22370 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
22380 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
22390 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
223a0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
223b0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
223c0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
223d0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
223e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
223f0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
22400 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
22410 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
22420 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
22430 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
22440 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
22450 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
22460 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
22470 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
22480 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
22490 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
224a0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
224b0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
224c0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
224d0 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
224e0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
224f0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
22500 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
22510 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
22520 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22530 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
22540 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
22550 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
22560 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
22570 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
22580 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
22590 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
225a0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
225b0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
225c0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
225d0 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
225e0 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
225f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
22600 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
22610 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
22620 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
22630 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
22640 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
22650 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
22660 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
22670 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
22680 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
22690 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
226a0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
226b0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
226c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
226d0 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
226e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
226f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
22700 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
22710 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
22720 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
22730 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
22740 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
22750 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
22760 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
22770 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
22780 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
22790 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
227a0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
227b0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
227c0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
227d0 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
227e0 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
227f0 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
22800 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
22810 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
22820 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
22830 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
22840 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
22850 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
22860 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
22870 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
22880 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
22890 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
228a0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
228b0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
228c0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
228d0 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
228e0 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
228f0 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
22900 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
22910 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
22920 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
22930 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
22940 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
22950 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
22960 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
22970 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
22980 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
22990 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
229a0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
229b0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
229c0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
229d0 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
229e0 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
229f0 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
22a00 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
22a10 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
22a20 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
22a30 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
22a40 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
22a50 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
22a60 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
22a70 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
22a80 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
22a90 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
22aa0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
22ab0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
22ac0 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
22ad0 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
22ae0 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
22af0 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
22b00 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
22b10 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
22b20 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
22b30 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
22b40 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
22b50 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
22b60 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
22b70 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
22b80 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
22b90 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
22ba0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
22bb0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
22bc0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
22bd0 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
22be0 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
22bf0 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
22c00 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
22c10 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
22c20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
22c30 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
22c40 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
22c50 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
22c60 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
22c70 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
22c80 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
22c90 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
22ca0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
22cb0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
22cc0 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
22cd0 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
22ce0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
22cf0 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
22d00 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
22d10 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
22d20 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
22d30 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
22d40 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
22d50 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
22d60 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
22d70 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
22d80 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
22d90 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
22da0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
22db0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
22dc0 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
22dd0 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
22de0 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
22df0 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
22e00 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
22e10 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
22e20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
22e30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
22e40 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
22e50 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
22e60 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
22e70 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
22e80 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
22e90 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
22ea0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
22eb0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
22ec0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
22ed0 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
22ee0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
22ef0 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
22f00 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
22f10 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
22f20 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
22f30 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
22f40 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
22f50 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
22f60 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
22f70 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
22f80 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
22f90 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
22fa0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
22fb0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
22fc0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
22fd0 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
22fe0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
22ff0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
23000 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
23010 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
23020 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
23030 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
23040 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
23050 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
23060 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
23070 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
23080 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
23090 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
230a0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
230b0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
230c0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
230d0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
230e0 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
230f0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
23100 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
23110 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
23120 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
23130 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
23140 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
23150 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
23160 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
23170 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
23180 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
23190 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
231a0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
231b0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
231c0 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
231d0 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
231e0 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
231f0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
23200 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
23210 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
23220 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
23230 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
23240 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
23250 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
23260 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
23270 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
23280 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
23290 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
232a0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
232b0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
232c0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
232d0 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
232e0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
232f0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
23300 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
23310 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
23320 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
23330 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
23340 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
23350 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
23360 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
23370 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
23380 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
23390 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
233a0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
233b0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
233c0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
233d0 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
233e0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
233f0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
23400 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
23410 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
23420 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
23430 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
23440 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
23450 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
23460 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
23470 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
23480 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
23490 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
234a0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
234b0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
234c0 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
234d0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
234e0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
234f0 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
23500 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
23510 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
23520 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
23530 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
23540 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
23550 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
23560 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
23570 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
23580 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
23590 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
235a0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
235b0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
235c0 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
235d0 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
235e0 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
235f0 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
23600 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
23610 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
23620 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
23630 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
23640 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
23650 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
23660 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
23670 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
23680 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
23690 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
236a0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
236b0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
236c0 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
236d0 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
236e0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
236f0 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
23700 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
23710 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
23720 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
23730 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
23740 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
23750 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
23760 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
23770 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
23780 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
23790 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
237a0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
237b0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
237c0 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
237d0 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
237e0 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
237f0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
23800 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
23810 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
23820 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
23830 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
23840 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
23850 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
23860 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
23870 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
23880 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
23890 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
238a0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
238b0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
238c0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
238d0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
238e0 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
238f0 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
23900 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
23910 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
23920 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
23930 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
23940 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
23950 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
23960 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
23970 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
23980 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
23990 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
239a0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
239b0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
239c0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
239d0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
239e0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
239f0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
23a00 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
23a10 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
23a20 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
23a30 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
23a40 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
23a50 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
23a60 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
23a70 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
23a80 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
23a90 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
23aa0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
23ab0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
23ac0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
23ad0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
23ae0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23af0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
23b00 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
23b10 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
23b20 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23b30 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
23b40 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
23b50 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
23b60 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
23b70 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
23b80 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
23b90 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
23ba0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
23bb0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23bc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23bd0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
23be0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
23bf0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
23c00 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
23c10 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
23c20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
23c30 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
23c40 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
23c50 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
23c60 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
23c70 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
23c80 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
23c90 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
23ca0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
23cb0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
23cc0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
23cd0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
23ce0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
23cf0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
23d00 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
23d10 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
23d20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
23d30 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
23d40 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
23d50 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
23d60 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
23d70 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
23d80 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
23d90 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
23da0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
23db0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
23dc0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23dd0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
23de0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
23df0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
23e00 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
23e10 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
23e20 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
23e30 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
23e40 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
23e50 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
23e60 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
23e70 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
23e80 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
23e90 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
23ea0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
23eb0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
23ec0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
23ed0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
23ee0 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
23ef0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
23f00 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
23f10 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
23f20 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
23f30 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
23f40 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
23f50 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
23f60 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
23f70 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
23f80 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
23f90 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
23fa0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
23fb0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
23fc0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
23fd0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
23fe0 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
23ff0 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
24000 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
24010 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
24020 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
24030 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
24040 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
24050 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
24060 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
24070 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
24080 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
24090 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
240a0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
240b0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
240c0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
240d0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
240e0 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
240f0 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
24100 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
24110 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
24120 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
24130 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
24140 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
24150 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
24160 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
24170 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
24180 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
24190 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
241a0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
241b0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
241c0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
241d0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
241e0 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
241f0 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
24200 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
24210 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
24220 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
24230 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
24240 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
24250 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
24260 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
24270 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
24280 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
24290 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
242a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
242b0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
242c0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
242d0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
242e0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
242f0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
24300 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
24310 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
24320 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
24330 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
24340 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
24350 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
24360 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
24370 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
24380 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
24390 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
243a0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
243b0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
243c0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
243d0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
243e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
243f0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
24400 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
24410 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
24420 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
24430 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
24440 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
24450 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
24460 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
24470 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
24480 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
24490 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
244a0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
244b0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
244c0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
244d0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
244e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
244f0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
24500 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
24510 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
24520 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
24530 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
24540 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
24550 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
24560 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
24570 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
24580 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
24590 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
245a0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
245b0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
245c0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
245d0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
245e0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
245f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
24600 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
24610 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
24620 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
24630 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
24640 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
24650 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
24660 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
24670 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
24680 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
24690 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
246a0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
246b0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
246c0 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
246d0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
246e0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
246f0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
24700 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
24710 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
24720 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
24730 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
24740 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
24750 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
24760 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
24770 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
24780 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
24790 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
247a0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
247b0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
247c0 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
247d0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
247e0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
247f0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
24800 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
24810 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
24820 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
24830 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
24840 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
24850 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
24860 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
24870 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
24880 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
24890 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
248a0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
248b0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
248c0 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
248d0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
248e0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
248f0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
24900 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
24910 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
24920 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
24930 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24940 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
24950 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
24960 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
24970 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
24980 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
24990 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
249a0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
249b0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
249c0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
249d0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
249e0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
249f0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
24a00 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
24a10 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
24a20 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
24a30 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
24a40 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
24a50 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24a60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
24a70 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
24a80 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
24a90 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
24aa0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
24ab0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
24ac0 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
24ad0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
24ae0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
24af0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
24b00 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
24b10 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24b20 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
24b30 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
24b40 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
24b50 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
24b60 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
24b70 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
24b80 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
24b90 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
24ba0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
24bb0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
24bc0 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
24bd0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
24be0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
24bf0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
24c00 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
24c10 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
24c20 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
24c30 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24c40 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
24c50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24c60 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
24c70 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
24c80 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
24c90 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
24ca0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
24cb0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
24cc0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
24cd0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
24ce0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
24cf0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
24d00 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
24d10 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
24d20 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
24d30 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
24d40 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
24d50 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
24d60 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24d70 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24d80 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
24d90 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24da0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
24db0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
24dc0 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
24dd0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
24de0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
24df0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
24e00 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
24e10 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
24e20 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
24e30 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
24e40 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
24e50 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
24e60 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
24e70 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
24e80 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24e90 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24ea0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
24eb0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
24ec0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
24ed0 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
24ee0 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
24ef0 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
24f00 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
24f10 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
24f20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
24f30 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
24f40 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
24f50 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
24f60 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
24f70 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
24f80 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
24f90 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
24fa0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
24fb0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
24fc0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
24fd0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
24fe0 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
24ff0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
25000 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
25010 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
25020 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
25030 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
25040 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
25050 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
25060 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
25070 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
25080 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
25090 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
250a0 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
250b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
250c0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
250d0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
250e0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
250f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
25100 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
25110 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
25120 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
25130 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
25140 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
25150 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
25160 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
25170 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
25180 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
25190 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
251a0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
251b0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
251c0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
251d0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
251e0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
251f0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
25200 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
25210 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
25220 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
25230 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
25240 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
25250 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
25260 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
25270 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
25280 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
25290 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
252a0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
252b0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
252c0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
252d0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
252e0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
252f0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
25300 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
25310 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
25320 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
25330 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
25340 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
25350 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
25360 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
25370 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
25380 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
25390 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
253a0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
253b0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
253c0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
253d0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
253e0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
253f0 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
25400 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
25410 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
25420 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
25430 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
25440 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
25450 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
25460 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
25470 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
25480 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
25490 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
254a0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
254b0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
254c0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
254d0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
254e0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
254f0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
25500 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
25510 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
25520 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
25530 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
25540 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
25550 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
25560 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
25570 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
25580 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
25590 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
255a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
255b0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
255c0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
255d0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
255e0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
255f0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
25600 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
25610 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
25620 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
25630 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
25640 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
25650 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
25660 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
25670 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
25680 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
25690 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
256a0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
256b0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
256c0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
256d0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
256e0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
256f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
25700 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
25710 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
25720 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
25730 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
25740 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
25750 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
25760 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
25770 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
25780 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
25790 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
257a0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
257b0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
257c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
257d0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
257e0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
257f0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
25800 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25810 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
25820 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
25830 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
25840 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
25850 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
25860 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
25870 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
25880 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
25890 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
258a0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
258b0 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
258c0 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
258d0 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
258e0 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
258f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
25900 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
25910 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
25920 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
25930 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
25940 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
25950 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
25960 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
25970 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
25980 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
25990 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
259a0 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
259b0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
259c0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
259d0 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
259e0 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
259f0 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
25a00 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
25a10 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
25a20 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
25a30 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
25a40 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
25a50 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
25a60 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
25a70 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
25a80 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
25a90 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
25aa0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
25ab0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
25ac0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
25ad0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
25ae0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
25af0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
25b00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25b10 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
25b20 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
25b30 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
25b40 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
25b50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
25b60 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
25b70 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
25b80 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
25b90 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
25ba0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
25bb0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
25bc0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25bd0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
25be0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
25bf0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
25c00 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
25c10 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
25c20 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
25c30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
25c40 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
25c50 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
25c60 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
25c70 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
25c80 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
25c90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
25ca0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
25cb0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
25cc0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
25cd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25ce0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
25cf0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
25d00 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
25d10 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
25d20 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
25d30 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
25d40 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
25d50 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
25d60 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
25d70 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
25d80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
25d90 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
25da0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
25db0 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
25dc0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
25dd0 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
25de0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
25df0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
25e00 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
25e10 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
25e20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
25e30 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
25e40 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
25e50 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
25e60 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
25e70 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
25e80 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
25e90 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
25ea0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
25eb0 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
25ec0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
25ed0 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
25ee0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
25ef0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
25f00 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
25f10 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
25f20 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
25f30 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
25f40 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
25f50 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
25f60 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
25f70 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
25f80 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
25f90 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
25fa0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
25fb0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
25fc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25fd0 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
25fe0 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
25ff0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
26000 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
26010 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
26020 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
26030 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
26040 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
26050 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
26060 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
26070 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
26080 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
26090 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
260a0 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
260b0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
260c0 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
260d0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
260e0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
260f0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
26100 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
26110 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
26120 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
26130 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
26140 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
26150 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
26160 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
26170 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
26180 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
26190 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
261a0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
261b0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
261c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
261d0 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
261e0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
261f0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
26200 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
26210 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
26220 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
26230 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
26240 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
26250 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
26260 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
26270 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
26280 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
26290 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
262a0 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
262b0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
262c0 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
262d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
262e0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
262f0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
26300 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
26310 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
26320 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
26330 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
26340 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
26350 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
26360 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
26370 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
26380 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
26390 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
263a0 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
263b0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
263c0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
263d0 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
263e0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
263f0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
26400 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
26410 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
26420 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
26430 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
26440 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
26450 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
26460 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
26470 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
26480 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
26490 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
264a0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
264b0 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
264c0 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
264d0 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
264e0 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
264f0 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
26500 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
26510 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
26520 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
26530 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
26540 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
26550 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
26560 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
26570 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
26580 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
26590 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
265a0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
265b0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
265c0 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
265d0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
265e0 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
265f0 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
26600 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26610 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
26620 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26630 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
26640 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26650 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
26660 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
26670 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
26680 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26690 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
266a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
266b0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
266c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
266d0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
266e0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
266f0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
26700 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
26710 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
26720 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
26730 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
26740 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
26750 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
26760 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
26770 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
26780 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26790 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
267a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
267b0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
267c0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
267d0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
267e0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
267f0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
26800 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26810 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
26820 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
26830 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
26840 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
26850 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26860 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26870 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
26880 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
26890 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
268a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
268b0 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
268c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
268d0 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
268e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
268f0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
26900 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
26910 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
26920 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
26930 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
26940 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
26950 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
26960 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
26970 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
26980 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
26990 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
269a0 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
269b0 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
269c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
269d0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
269e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
269f0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
26a00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26a10 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26a20 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
26a30 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
26a40 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26a50 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
26a60 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26a70 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
26a80 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26a90 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
26aa0 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
26ab0 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
26ac0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
26ad0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
26ae0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
26af0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
26b00 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
26b10 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
26b20 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26b30 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
26b40 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
26b50 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
26b60 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
26b70 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
26b80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26b90 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
26ba0 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
26bb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
26bc0 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
26bd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26be0 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
26bf0 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
26c00 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
26c10 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
26c20 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26c30 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
26c40 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26c50 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
26c60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26c70 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
26c80 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
26c90 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
26ca0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26cb0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
26cc0 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EADS]] ^(<dt>SQL
26cd0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
26ce0 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a  _THREADS</dt>.**
26cf0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26d00 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c   number of auxil
26d10 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65  iary worker thre
26d20 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c  ads that a singl
26d30 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
26d40 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74  tatement] may st
26d50 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  art.</dd>)^.** <
26d60 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
26d70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
26d80 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
26d90 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
26da0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
26db0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
26dc0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
26dd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
26de0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
26df0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
26e00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26e10 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
26e20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
26e30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26e40 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
26e50 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
26e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26e70 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
26e80 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
26e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26ea0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
26eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
26ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26ed0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
26ee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
26ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26f00 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
26f10 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
26f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26f30 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
26f40 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
26f50 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
26f60 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
26f70 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
26f80 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
26f90 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
26fa0 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20  HREADS          
26fb0 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   11../*.** CAPI3
26fc0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
26fd0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
26fe0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
26ff0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
27000 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  iler}.** METHOD:
27010 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53   sqlite3.** CONS
27020 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
27030 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  _stmt.**.** To e
27040 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
27050 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
27060 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
27070 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
27080 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
27090 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
270a0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
270b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
270c0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
270d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
270e0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
270f0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
27100 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
27110 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
27120 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
27130 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
27140 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
27150 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
27160 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
27170 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
27180 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
27190 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
271a0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
271b0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
271c0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
271d0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
271e0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
271f0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
27200 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
27210 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
27220 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
27230 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
27240 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
27250 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
27260 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
27270 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
27280 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
27290 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65  ment is negative
272a0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
272b0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
272c0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
272d0 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
272e0 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  e is positive, t
272f0 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a  hen it is the.**
27300 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
27310 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
27320 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a    ^If nByte is z
27330 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65  ero, then no pre
27340 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
27350 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e  nt is generated.
27360 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65  .** If the calle
27370 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65  r knows that the
27380 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
27390 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
273a0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72  ed, then.** ther
273b0 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72  e is a small per
273c0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
273d0 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e  ge to passing an
273e0 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
273f0 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20   that.** is the 
27400 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
27410 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
27420 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
27430 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
27440 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
27450 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
27460 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
27470 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
27480 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
27490 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
274a0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
274b0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
274c0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
274d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
274e0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
274f0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
27500 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
27510 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
27520 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
27530 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
27540 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
27550 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
27560 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
27570 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
27580 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
27590 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
275a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
275b0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
275c0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
275d0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
275e0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
275f0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
27600 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
27610 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
27620 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
27630 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
27640 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
27650 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
27660 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
27670 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
27680 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
27690 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
276a0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
276b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
276c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
276d0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
276e0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
276f0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
27700 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
27710 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
27720 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
27730 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
27740 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
27750 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
27760 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
27770 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
27780 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27790 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
277a0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
277b0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
277c0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
277d0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
277e0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
277f0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
27800 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
27810 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
27820 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
27830 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
27840 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
27850 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
27860 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
27870 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
27880 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
27890 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
278a0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
278b0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
278c0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
278d0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
278e0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
278f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
27900 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
27910 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
27920 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
27930 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
27940 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
27950 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
27960 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
27970 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
27980 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
27990 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
279a0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
279b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
279c0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
279d0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
279e0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
279f0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
27a00 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
27a10 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
27a20 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
27a30 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
27a40 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
27a50 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
27a60 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
27a70 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
27a80 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
27a90 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
27aa0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
27ab0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
27ac0 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
27ad0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
27ae0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
27af0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
27b00 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
27b10 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
27b20 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
27b30 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
27b40 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
27b50 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
27b60 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
27b70 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
27b80 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
27b90 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
27ba0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
27bb0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
27bc0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
27bd0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
27be0 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
27bf0 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
27c00 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
27c10 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
27c20 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
27c30 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
27c40 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
27c50 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
27c60 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
27c70 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
27c80 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
27c90 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
27ca0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
27cb0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
27cc0 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
27cd0 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
27ce0 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
27cf0 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
27d00 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
27d10 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
27d20 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
27d30 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
27d40 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
27d50 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
27d60 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
27d70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
27d80 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
27d90 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
27da0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
27db0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
27dc0 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
27dd0 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
27de0 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
27df0 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
27e00 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
27e10 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
27e20 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
27e30 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
27e40 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
27e50 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
27e60 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
27e70 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
27e80 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
27e90 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
27ea0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
27eb0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
27ec0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
27ed0 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
27ee0 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
27ef0 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
27f00 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
27f10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
27f20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
27f30 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
27f40 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
27f50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
27f60 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
27f70 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
27f80 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
27f90 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
27fa0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
27fb0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
27fc0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
27fd0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
27fe0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27ff0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
28000 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
28010 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
28020 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
28030 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
28040 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
28050 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
28060 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
28070 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
28080 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
28090 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
280a0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
280b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
280c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
280d0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
280e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
280f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28100 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
28110 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
28120 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
28130 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
28140 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28150 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
28160 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
28170 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
28180 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
28190 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
281a0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
281b0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
281c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
281d0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
281e0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
281f0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
28200 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
28210 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
28220 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
28230 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
28240 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28250 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
28260 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
28270 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28280 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28290 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
282a0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
282b0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
282c0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
282d0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
282e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
282f0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
28300 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
28310 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
28320 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28330 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
28340 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
28350 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
28360 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28370 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28380 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
28390 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
283a0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
283b0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
283c0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
283d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
283e0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
283f0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28400 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28410 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28420 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28430 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
28440 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d  atement SQL.** M
28450 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
28460 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
28470 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
28480 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
28490 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
284a0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
284b0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
284c0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
284d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
284e0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
284f0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
28500 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
28510 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28520 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
28530 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
28540 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
28550 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
28560 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
28570 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
28580 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
28590 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
285a0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
285b0 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f  atabase.** METHO
285c0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
285d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
285e0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
285f0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
28600 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
28610 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
28620 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
28630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28640 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
28650 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
28660 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
28670 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
28680 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
28690 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
286a0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
286b0 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
286c0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
286d0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
286e0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
286f0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
28700 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
28710 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
28720 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
28730 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
28740 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
28750 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
28760 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
28770 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
28780 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
28790 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
287a0 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
287b0 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
287c0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
287d0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
287e0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
287f0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
28800 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
28810 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
28820 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
28830 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
28840 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
28850 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
28860 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
28870 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
28880 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
28890 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
288a0 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
288b0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
288c0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
288d0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
288e0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
288f0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
28900 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
28910 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
28920 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
28930 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
28940 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
28950 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
28960 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
28970 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
28980 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
28990 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
289a0 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
289b0 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
289c0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
289d0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
289e0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
289f0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
28a00 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
28a10 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
28a20 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
28a30 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
28a40 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
28a50 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
28a60 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
28a70 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
28a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
28a90 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
28aa0 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
28ab0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
28ac0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28ad0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
28ae0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
28af0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
28b00 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
28b10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28b20 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
28b30 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
28b40 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
28b50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28b60 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
28b70 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
28b80 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
28b90 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
28ba0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
28bb0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
28bc0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
28bd0 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
28be0 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
28bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
28c00 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f  p(S)] but has no
28c10 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  t run to complet
28c20 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e  ion and/or has n
28c30 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  ot .** been rese
28c40 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
28c50 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
28c60 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
28c70 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
28c80 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
28c90 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
28ca0 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
28cb0 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
28cc0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
28cd0 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
28ce0 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
28cf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
28d00 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
28d10 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
28d20 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
28d30 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
28d40 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
28d50 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
28d60 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
28d70 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
28d80 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
28d90 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
28da0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
28db0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
28dc0 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
28dd0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
28de0 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
28df0 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
28e00 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
28e10 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
28e20 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
28e30 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
28e40 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
28e50 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
28e60 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
28e70 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
28e80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
28e90 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
28ea0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
28eb0 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
28ec0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
28ed0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
28ee0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
28ef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
28f00 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
28f10 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
28f20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
28f30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28f40 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
28f50 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
28f60 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
28f70 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
28f80 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
28f90 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
28fa0 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
28fb0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
28fc0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
28fd0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
28fe0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
28ff0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
29000 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
29010 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
29020 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
29030 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
29040 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
29050 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
29060 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
29070 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
29080 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
29090 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
290a0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
290b0 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
290c0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
290d0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
290e0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
290f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29100 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
29110 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
29120 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
29130 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
29140 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
29150 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
29160 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
29170 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68  lite3_value.  Th
29180 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  e.** [sqlite3_va
29190 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72  lue_dup()] inter
291a0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
291b0 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20   to construct a 
291c0 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65  new .** protecte
291d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
291e0 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63  from an unprotec
291f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29200 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
29210 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
29220 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
29230 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
29240 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
29250 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
29260 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
29270 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
29280 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
29290 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
292a0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
292b0 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
292c0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
292d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
292e0 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
292f0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
29300 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
29310 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
29320 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
29330 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
29340 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
29350 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
29360 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
29370 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
29380 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
29390 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
293a0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
293b0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
293c0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
293d0 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
293e0 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
293f0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
29400 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
29410 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
29420 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
29430 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
29440 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
29450 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
29460 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
29470 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
29480 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
29490 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
294a0 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
294b0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
294c0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
294d0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
294e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
294f0 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
29500 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
29510 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
29520 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
29530 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
29540 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
29550 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
29560 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
29570 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
29580 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
29590 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
295a0 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
295b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
295c0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
295d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
295e0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
295f0 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
29600 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
29610 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29620 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
29630 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
29640 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
29650 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
29660 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
29670 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
29680 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
29690 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
296a0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
296b0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
296c0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
296d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
296e0 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
296f0 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
29700 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
29710 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
29720 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
29730 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
29740 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
29750 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
29760 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
29770 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
29780 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
29790 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
297a0 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
297b0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
297c0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
297d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
297e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
297f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
29800 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
29810 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
29820 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
29830 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
29840 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
29850 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
29860 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
29870 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
29880 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
29890 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
298a0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
298b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
298c0 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
298d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
298e0 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
298f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
29900 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
29910 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
29920 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
29930 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
29940 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
29950 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
29960 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
29970 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
29980 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
29990 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
299a0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
299b0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
299c0 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
299d0 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
299e0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
299f0 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
29a00 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
29a10 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d  er binding}.** M
29a20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
29a30 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  tmt.**.** ^(In t
29a40 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
29a50 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
29a60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29a70 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
29a80 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
29a90 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
29aa0 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
29ab0 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
29ac0 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
29ad0 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
29ae0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
29af0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
29b00 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
29b10 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
29b20 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
29b30 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
29b40 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
29b50 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
29b60 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
29b70 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
29b80 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
29b90 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
29ba0 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
29bb0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
29bc0 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
29bd0 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
29be0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
29bf0 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
29c00 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
29c10 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
29c20 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29c30 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
29c40 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
29c50 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
29c60 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
29c70 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
29c80 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
29c90 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
29ca0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
29cb0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
29cc0 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
29cd0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29ce0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
29cf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
29d00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
29d10 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
29d20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
29d30 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
29d40 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
29d50 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
29d60 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
29d70 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
29d80 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
29d90 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
29da0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
29db0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
29dc0 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
29dd0 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
29de0 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
29df0 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
29e00 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
29e10 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
29e20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
29e30 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
29e40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29e50 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
29e60 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
29e70 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
29e80 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
29e90 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
29ea0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
29eb0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
29ec0 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
29ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
29ee0 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
29ef0 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
29f00 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
29f10 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
29f20 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
29f30 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
29f40 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
29f50 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
29f60 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
29f70 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
29f80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
29f90 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
29fa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29fb0 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
29fc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
29fd0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29fe0 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
29ff0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
2a000 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
2a010 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
2a020 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
2a030 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
2a040 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
2a050 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
2a060 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
2a070 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
2a080 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2a090 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2a0a0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
2a0b0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
2a0c0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2a0d0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
2a0e0 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
2a0f0 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
2a100 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2a110 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
2a120 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2a130 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a140 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2a150 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2a160 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
2a170 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
2a180 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
2a190 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2a1a0 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
2a1b0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
2a1c0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
2a1d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2a1e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2a1f0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
2a200 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
2a210 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2a220 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2a230 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
2a240 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2a250 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
2a260 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a270 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
2a280 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
2a290 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2a2a0 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a  text64() then.**
2a2b0 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
2a2c0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
2a2d0 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
2a2e0 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
2a2f0 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
2a300 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
2a310 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
2a320 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
2a330 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
2a340 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
2a350 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
2a360 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
2a370 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2a380 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
2a390 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
2a3a0 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
2a3b0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
2a3c0 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
2a3d0 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
2a3e0 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
2a3f0 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
2a400 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
2a410 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2a420 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
2a430 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61  nt to the BLOB a
2a440 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e  nd string bindin
2a450 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  g interfaces.** 
2a460 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2a470 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
2a480 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
2a490 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
2a4a0 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
2a4b0 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
2a4c0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2a4d0 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
2a4e0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2a4f0 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
2a500 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62  if the call to b
2a510 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a  ind API fails..*
2a520 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2a530 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
2a540 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
2a550 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
2a560 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
2a570 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
2a580 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
2a590 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
2a5a0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
2a5b0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2a5c0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
2a5d0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2a5e0 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
2a5f0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
2a600 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
2a610 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
2a620 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2a630 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
2a640 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
2a650 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
2a660 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2a670 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2a680 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d  ^The sixth argum
2a690 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2a6a0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73  ind_text64() mus
2a6b0 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b  t be one of.** [
2a6c0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
2a6d0 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
2a6e0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
2a6f0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2a700 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66  LE].** to specif
2a710 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  y the encoding o
2a720 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68  f the text in th
2a730 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2a740 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69  r.  If.** the si
2a750 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2a760 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a770 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  t64() is not one
2a780 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77   of the.** allow
2a790 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20  ed values shown 
2a7a0 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65  above, or if the
2a7b0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
2a7c0 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66  s different.** f
2a7d0 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  rom the encoding
2a7e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2a7f0 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
2a800 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  r, then the beha
2a810 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66  vior.** is undef
2a820 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2a830 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2a840 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
2a850 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
2a860 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
2a870 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
2a880 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
2a890 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
2a8a0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
2a8b0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
2a8c0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
2a8d0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
2a8e0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
2a8f0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
2a900 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
2a910 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
2a920 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
2a930 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
2a940 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
2a950 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
2a960 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
2a970 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
2a980 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
2a990 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
2a9a0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
2a9b0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
2a9c0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
2a9d0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
2a9e0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
2a9f0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2aa00 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2aa10 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
2aa20 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
2aa30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2aa40 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
2aa50 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2aa60 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
2aa70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2aa80 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
2aa90 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
2aaa0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
2aab0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
2aac0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
2aad0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
2aae0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
2aaf0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
2ab00 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
2ab10 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
2ab20 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2ab30 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2ab40 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
2ab50 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2ab60 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
2ab70 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
2ab80 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
2ab90 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
2aba0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
2abb0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
2abc0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
2abd0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
2abe0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2abf0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
2ac00 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2ac10 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2ac20 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
2ac30 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
2ac40 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
2ac50 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
2ac60 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62  _TOOBIG] might b
2ac70 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
2ac80 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69  e size of a stri
2ac90 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78  ng or BLOB.** ex
2aca0 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70  ceeds limits imp
2acb0 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
2acc0 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2acd0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f  LIMIT_LENGTH]) o
2ace0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  r.** [SQLITE_MAX
2acf0 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53  _LENGTH]..** ^[S
2ad00 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
2ad10 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2ad20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
2ad30 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2ad40 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
2ad50 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
2ad60 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
2ad70 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
2ad80 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2ad90 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2ada0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2adb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2adc0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
2add0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ade0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2adf0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2ae00 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
2ae10 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2ae20 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
2ae30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2ae40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2ae50 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
2ae60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2ae70 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
2ae80 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2ae90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2aea0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2aeb0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2aec0 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
2aed0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2aee0 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
2aef0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
2af00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2af10 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
2af20 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
2af30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2af40 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
2af50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2af60 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
2af70 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
2af80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2af90 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2afa0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
2afb0 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  *,int,void(*)(vo
2afc0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2afd0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
2afe0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2aff0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2b000 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2b010 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2b020 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71  3_bind_text64(sq
2b030 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b040 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
2b050 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2b060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b070 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2b080 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
2b090 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
2b0a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2b0b0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
2b0c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2b0d0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
2b0e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b0f0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
2b100 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2b110 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c   int n);.int sql
2b120 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2b130 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2b140 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2b150 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  _uint64);../*.**
2b160 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2b170 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
2b180 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ers.** METHOD: s
2b190 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2b1a0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
2b1b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
2b1c0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
2b1d0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
2b1e0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
2b1f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2b200 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
2b210 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
2b220 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
2b230 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
2b240 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
2b250 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
2b260 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
2b270 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
2b280 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
2b290 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
2b2a0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
2b2b0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
2b2c0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
2b2d0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
2b2e0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
2b2f0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
2b300 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
2b310 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
2b320 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
2b330 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
2b340 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
2b350 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
2b360 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
2b370 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
2b380 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
2b390 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
2b3a0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
2b3b0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
2b3c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
2b3d0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2b3e0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2b3f0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2b400 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b410 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
2b420 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2b430 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2b440 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2b450 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b460 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
2b470 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2b480 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
2b490 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
2b4a0 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  er.** METHOD: sq
2b4b0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2b4c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2b4d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2b4e0 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
2b4f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2b500 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
2b510 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
2b520 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
2b530 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2b540 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
2b550 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2b560 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2b570 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2b580 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
2b590 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
2b5a0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
2b5b0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2b5c0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2b5d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2b5e0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2b5f0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
2b600 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
2b610 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
2b620 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
2b630 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
2b640 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
2b650 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
2b660 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
2b670 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
2b680 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
2b690 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
2b6a0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
2b6b0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
2b6c0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
2b6d0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
2b6e0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2b6f0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
2b700 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
2b710 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
2b720 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
2b730 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
2b740 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
2b750 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
2b760 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2b770 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
2b780 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
2b790 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
2b7a0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
2b7b0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
2b7c0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
2b7d0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
2b7e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b7f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2b800 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2b810 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2b820 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2b830 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2b840 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2b850 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b860 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
2b870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2b880 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2b890 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
2b8a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
2b8b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2b8c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b8d0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2b8e0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
2b8f0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
2b900 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
2b910 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b920 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
2b930 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
2b940 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
2b950 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
2b960 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
2b970 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2b980 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
2b990 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
2b9a0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
2b9b0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
2b9c0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2b9d0 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
2b9e0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
2b9f0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
2ba00 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
2ba10 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
2ba20 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
2ba30 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
2ba40 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
2ba50 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
2ba60 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
2ba70 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
2ba80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
2ba90 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2baa0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2bab0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2bac0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2bad0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2bae0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2baf0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2bb00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2bb10 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2bb20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2bb30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2bb40 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
2bb50 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
2bb60 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
2bb70 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2bb80 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
2bb90 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2bba0 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
2bbb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2bbc0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
2bbd0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
2bbe0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
2bbf0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
2bc00 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
2bc10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2bc20 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
2bc30 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2bc40 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
2bc50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2bc60 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
2bc70 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
2bc80 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
2bc90 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2bca0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
2bcb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bcc0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
2bcd0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
2bce0 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
2bcf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2bd00 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
2bd10 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2bd20 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2bd30 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
2bd40 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2bd50 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
2bd60 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
2bd70 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
2bd80 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
2bd90 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
2bda0 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
2bdb0 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
2bdc0 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  PDATE])..**.** S
2bdd0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2bde0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
2bdf0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2be00 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
2be10 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2be20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2be30 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
2be40 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2be50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2be60 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2be70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2be80 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
2be90 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
2bea0 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
2beb0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2bec0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
2bed0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
2bee0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2bef0 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
2bf00 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2bf10 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2bf20 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2bf30 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
2bf40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2bf50 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
2bf60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2bf70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
2bf80 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
2bf90 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
2bfa0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
2bfb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bfc0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
2bfd0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
2bfe0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
2bff0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2c000 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
2c010 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
2c020 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2c030 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
2c040 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
2c050 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
2c060 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
2c070 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
2c080 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c090 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
2c0a0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2c0b0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2c0c0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2c0d0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2c0e0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2c0f0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2c100 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2c110 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2c120 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2c130 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
2c140 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2c150 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2c160 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2c170 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
2c180 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
2c190 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
2c1a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
2c1b0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
2c1c0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
2c1d0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
2c1e0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
2c1f0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
2c200 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
2c210 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
2c220 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2c230 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2c240 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
2c250 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
2c260 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
2c270 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
2c280 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
2c290 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
2c2a0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
2c2b0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
2c2c0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
2c2d0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
2c2e0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
2c2f0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
2c300 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
2c310 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
2c320 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
2c330 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2c340 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
2c350 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2c360 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
2c370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c380 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2c390 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
2c3a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
2c3b0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
2c3c0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2c3d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c3e0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2c3f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
2c400 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
2c410 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
2c420 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2c430 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
2c440 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
2c450 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
2c460 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
2c470 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
2c480 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
2c490 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2c4a0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
2c4b0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
2c4c0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
2c4d0 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
2c4e0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
2c4f0 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
2c500 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
2c510 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
2c520 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
2c530 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
2c540 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
2c550 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
2c560 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
2c570 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
2c580 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
2c590 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2c5a0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
2c5b0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
2c5c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
2c5d0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
2c5e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2c5f0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2c600 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2c610 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2c620 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2c630 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
2c640 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2c650 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
2c660 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
2c670 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
2c680 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
2c690 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
2c6a0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
2c6b0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
2c6c0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
2c6d0 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
2c6e0 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
2c6f0 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
2c700 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2c710 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
2c720 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2c730 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
2c740 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
2c750 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c760 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
2c770 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
2c780 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2c790 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
2c7a0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2c7b0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
2c7c0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
2c7d0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
2c7e0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
2c7f0 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
2c800 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
2c810 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
2c820 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
2c830 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2c840 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
2c850 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
2c860 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
2c870 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
2c880 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
2c890 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
2c8a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2c8b0 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
2c8c0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
2c8d0 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
2c8e0 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
2c8f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2c900 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
2c910 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
2c920 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
2c930 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
2c940 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
2c950 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
2c960 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
2c970 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
2c980 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
2c990 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
2c9a0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
2c9b0 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
2c9c0 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
2c9d0 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
2c9e0 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
2c9f0 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
2ca00 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
2ca10 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
2ca20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
2ca30 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
2ca40 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
2ca50 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
2ca60 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
2ca70 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
2ca80 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
2ca90 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
2caa0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2cab0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2cac0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
2cad0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
2cae0 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
2caf0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
2cb00 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
2cb10 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2cb20 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2cb30 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
2cb40 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
2cb50 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2cb60 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2cb70 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2cb80 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2cb90 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
2cba0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
2cbb0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
2cbc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cbd0 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
2cbe0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
2cbf0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2cc00 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2cc10 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
2cc20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2cc30 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2cc40 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
2cc50 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2cc60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2cc70 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2cc80 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2cc90 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2cca0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2ccb0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2ccc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2ccd0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2cce0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ccf0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
2cd00 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2cd10 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2cd20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2cd30 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
2cd40 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2cd50 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2cd60 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2cd70 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2cd80 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2cd90 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
2cda0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
2cdb0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2cdc0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2cdd0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
2cde0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2cdf0 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
2ce00 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2ce10 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
2ce20 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
2ce30 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
2ce40 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2ce50 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
2ce60 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
2ce70 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
2ce80 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
2ce90 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
2cea0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
2ceb0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
2cec0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
2ced0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
2cee0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
2cef0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2cf00 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2cf10 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
2cf20 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2cf30 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
2cf40 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2cf50 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
2cf60 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2cf70 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
2cf80 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
2cf90 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
2cfa0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
2cfb0 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
2cfc0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
2cfd0 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
2cfe0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
2cff0 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
2d000 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
2d010 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
2d020 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
2d030 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
2d040 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
2d050 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
2d060 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
2d070 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
2d080 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
2d090 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
2d0a0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
2d0b0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
2d0c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2d0d0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
2d0e0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
2d0f0 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
2d100 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
2d110 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
2d120 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
2d130 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
2d140 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
2d150 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
2d160 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
2d170 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2d180 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
2d190 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
2d1a0 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
2d1b0 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
2d1c0 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
2d1d0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
2d1e0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
2d1f0 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
2d200 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
2d210 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
2d220 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
2d230 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2d240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2d250 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2d260 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2d270 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2d280 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
2d290 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d2a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d2b0 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
2d2c0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
2d2d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d2e0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  _stmt.**.** Afte
2d2f0 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
2d300 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
2d310 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
2d320 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
2d330 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2d340 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2d350 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2d360 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
2d370 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
2d380 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d390 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
2d3a0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
2d3b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
2d3c0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
2d3d0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
2d3e0 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
2d3f0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
2d400 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
2d410 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2d420 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2d430 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
2d440 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
2d450 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
2d460 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
2d470 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
2d480 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
2d490 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d4a0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2d4b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2d4c0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
2d4d0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2d4e0 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
2d4f0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2d500 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2d510 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
2d520 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
2d530 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2d540 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
2d550 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
2d560 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
2d570 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
2d580 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
2d590 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
2d5a0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2d5b0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
2d5c0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
2d5d0 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
2d5e0 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
2d5f0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
2d600 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
2d610 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
2d620 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
2d630 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
2d640 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
2d650 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
2d660 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
2d670 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2d680 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
2d690 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
2d6a0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2d6b0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
2d6c0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
2d6d0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
2d6e0 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
2d6f0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
2d700 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
2d710 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
2d720 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2d730 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
2d740 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
2d750 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
2d760 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
2d770 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
2d780 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
2d790 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
2d7a0 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
2d7b0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
2d7c0 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
2d7d0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2d7e0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
2d7f0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
2d800 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
2d810 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
2d820 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2d830 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
2d840 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2d850 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
2d860 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
2d870 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
2d880 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2d890 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2d8a0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
2d8b0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
2d8c0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
2d8d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2d8e0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
2d8f0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
2d900 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
2d910 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
2d920 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
2d930 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
2d940 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
2d950 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
2d960 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
2d970 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
2d980 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
2d990 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
2d9a0 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
2d9b0 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
2d9c0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
2d9d0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
2d9e0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
2d9f0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2da00 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
2da10 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
2da20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
2da30 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
2da40 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
2da50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
2da60 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
2da70 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
2da80 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
2da90 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
2daa0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
2dab0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2dac0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2dad0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
2dae0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
2daf0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
2db00 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
2db10 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
2db20 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
2db30 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2db40 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
2db50 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
2db60 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
2db70 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
2db80 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2db90 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
2dba0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
2dbb0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
2dbc0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
2dbd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2dbe0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
2dbf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2dc00 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
2dc10 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
2dc20 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2dc30 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
2dc40 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
2dc50 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2dc60 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
2dc70 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
2dc80 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
2dc90 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
2dca0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
2dcb0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
2dcc0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
2dcd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dce0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
2dcf0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
2dd00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
2dd10 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
2dd20 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
2dd30 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
2dd40 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
2dd50 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
2dd60 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
2dd70 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
2dd80 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
2dd90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2dda0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
2ddb0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
2ddc0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
2ddd0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
2dde0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
2ddf0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
2de00 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
2de10 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
2de20 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
2de30 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
2de40 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
2de50 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
2de60 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
2de70 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
2de80 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2de90 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
2dea0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2deb0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
2dec0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
2ded0 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
2dee0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2def0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
2df00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2df10 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
2df20 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
2df30 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
2df40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2df50 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
2df60 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
2df70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2df80 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
2df90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2dfa0 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
2dfb0 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
2dfc0 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
2dfd0 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
2dfe0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2dff0 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
2e000 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
2e010 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
2e020 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
2e030 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
2e040 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
2e050 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
2e060 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
2e070 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
2e080 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
2e090 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
2e0a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
2e0b0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
2e0c0 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
2e0d0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
2e0e0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
2e0f0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
2e100 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
2e110 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
2e120 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
2e130 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
2e140 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
2e150 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
2e160 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
2e170 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
2e180 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
2e190 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
2e1a0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2e1b0 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
2e1c0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2e1d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2e1e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
2e1f0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
2e200 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
2e210 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2e220 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
2e230 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
2e240 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
2e250 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
2e260 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
2e270 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
2e280 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
2e290 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2e2a0 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
2e2b0 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
2e2c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
2e2d0 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
2e2e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2e2f0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2e300 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2e310 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
2e320 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
2e330 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2e340 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2e350 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
2e360 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
2e370 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
2e380 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
2e390 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
2e3a0 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
2e3b0 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
2e3c0 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
2e3d0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2e3e0 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
2e3f0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
2e400 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2e410 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2e420 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2e430 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
2e440 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2e450 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2e460 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2e470 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
2e480 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2e490 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2e4a0 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
2e4b0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2e4c0 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
2e4d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e4e0 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
2e4f0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
2e500 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
2e510 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
2e520 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
2e530 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
2e540 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
2e550 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
2e560 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
2e570 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
2e580 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2e590 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
2e5a0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2e5b0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2e5c0 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
2e5d0 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
2e5e0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
2e5f0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2e600 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
2e610 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
2e620 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2e630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2e640 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
2e650 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
2e660 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2e670 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
2e680 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
2e690 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
2e6a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2e6b0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2e6c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
2e6d0 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
2e6e0 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
2e6f0 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
2e700 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
2e710 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
2e720 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
2e730 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
2e740 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
2e750 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
2e760 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
2e770 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2e780 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e790 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2e7a0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2e7b0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2e7c0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2e7d0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
2e7e0 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
2e7f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
2e800 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
2e810 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
2e820 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
2e830 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
2e840 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
2e850 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2e860 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2e870 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
2e880 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
2e890 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2e8a0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
2e8b0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
2e8c0 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
2e8d0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
2e8e0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
2e8f0 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
2e900 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
2e910 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
2e920 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
2e930 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
2e940 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
2e950 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
2e960 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
2e970 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
2e980 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
2e990 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
2e9a0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
2e9b0 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
2e9c0 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
2e9d0 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
2e9e0 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
2e9f0 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
2ea00 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
2ea10 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
2ea20 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
2ea30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
2ea40 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
2ea50 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
2ea60 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
2ea70 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
2ea80 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
2ea90 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2eaa0 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
2eab0 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
2eac0 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
2ead0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2eae0 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
2eaf0 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
2eb00 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
2eb10 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
2eb20 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2eb30 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2eb40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2eb50 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2eb60 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
2eb70 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
2eb80 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
2eb90 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
2eba0 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
2ebb0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2ebc0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
2ebd0 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
2ebe0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2ebf0 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
2ec00 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
2ec10 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
2ec20 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2ec30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
2ec40 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2ec50 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
2ec60 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
2ec70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2ec80 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2ec90 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
2eca0 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
2ecb0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
2ecc0 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
2ecd0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
2ece0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
2ecf0 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
2ed00 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
2ed10 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2ed20 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
2ed30 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
2ed40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2ed50 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
2ed60 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
2ed70 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2ed80 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
2ed90 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
2eda0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
2edb0 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
2edc0 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
2edd0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2ede0 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
2edf0 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
2ee00 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
2ee10 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2ee20 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2ee30 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2ee40 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2ee50 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
2ee60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2ee70 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
2ee80 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
2ee90 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2eea0 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
2eeb0 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
2eec0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2eed0 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
2eee0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2eef0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2ef00 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
2ef10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ef20 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
2ef30 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
2ef40 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2ef50 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
2ef60 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2ef70 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
2ef80 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2ef90 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2efa0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2efb0 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
2efc0 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
2efd0 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
2efe0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2eff0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
2f000 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
2f010 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2f020 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2f030 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f040 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
2f050 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
2f060 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2f070 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
2f080 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
2f090 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
2f0a0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
2f0b0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2f0c0 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
2f0d0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2f0e0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
2f0f0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
2f100 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
2f110 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
2f120 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
2f130 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2f140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f150 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
2f160 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
2f170 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
2f180 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
2f190 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
2f1a0 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
2f1b0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
2f1c0 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
2f1d0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2f1e0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2f1f0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
2f200 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
2f210 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
2f220 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
2f230 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
2f240 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
2f250 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
2f260 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
2f270 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2f280 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2f290 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
2f2a0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2f2b0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
2f2c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2f2d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2f2e0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2f2f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2f300 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2f310 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
2f320 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2f330 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
2f340 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2f350 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
2f360 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2f370 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2f380 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2f390 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2f3a0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2f3b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f3c0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2f3d0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2f3e0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2f3f0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
2f400 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2f410 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2f420 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2f430 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2f440 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2f450 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2f460 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f470 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2f480 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2f490 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2f4a0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
2f4b0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2f4c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f4d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2f4e0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2f4f0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2f500 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2f510 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2f520 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
2f530 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2f540 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f550 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2f560 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2f570 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
2f580 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2f590 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2f5a0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2f5b0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2f5c0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2f5d0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
2f5e0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2f5f0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2f600 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2f610 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
2f620 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2f630 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2f640 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2f650 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2f660 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2f670 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2f680 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
2f690 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2f6a0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
2f6b0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2f6c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f6d0 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
2f6e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f6f0 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
2f700 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
2f710 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
2f720 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
2f730 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
2f740 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
2f750 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
2f760 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f770 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
2f780 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f790 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
2f7a0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
2f7b0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
2f7c0 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
2f7d0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2f7e0 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
2f7f0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2f800 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f810 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
2f820 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
2f830 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
2f840 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
2f850 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2f860 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
2f870 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
2f880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2f890 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
2f8a0 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
2f8b0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2f8c0 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f  ** <b>Warning:</
2f8d0 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  b> ^The object r
2f8e0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2f8f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2f900 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
2f910 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f920 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
2f930 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65    In a multithre
2f940 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  aded environment
2f950 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63  ,.** an unprotec
2f960 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2f970 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c  e object may onl
2f980 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79  y be used safely
2f990 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
2f9a0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
2f9b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
2f9c0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
2f9d0 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
2f9e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f9f0 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
2fa00 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2fa10 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2fa20 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
2fa30 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
2fa40 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
2fa50 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
2fa60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fa70 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
2fa80 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
2fa90 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
2faa0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
2fab0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e  he behavior is n
2fac0 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a  ot threadsafe..*
2fad0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2fae0 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
2faf0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2fb00 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
2fb10 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
2fb20 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
2fb30 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
2fb40 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
2fb50 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
2fb60 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
2fb70 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2fb80 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
2fb90 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
2fba0 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
2fbb0 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
2fbc0 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
2fbd0 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
2fbe0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
2fbf0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
2fc00 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
2fc10 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
2fc20 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
2fc30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
2fc40 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
2fc50 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
2fc60 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
2fc70 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
2fc80 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2fc90 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2fca0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
2fcb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2fcc0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2fcd0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2fce0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
2fcf0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2fd00 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
2fd10 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
2fd20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2fd30 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2fd40 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2fd50 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
2fd60 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2fd70 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2fd80 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2fd90 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2fda0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
2fdb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2fdc0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
2fdd0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2fde0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2fdf0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2fe00 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2fe10 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2fe20 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
2fe30 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
2fe40 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2fe50 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2fe60 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2fe70 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2fe80 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
2fe90 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2fea0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2feb0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
2fec0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2fed0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2fee0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42  > [CAST] to BLOB
2fef0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2ff00 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
2ff10 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2ff20 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2ff30 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2ff40 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2ff50 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
2ff60 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
2ff70 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
2ff80 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
2ff90 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
2ffa0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2ffb0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2ffc0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
2ffd0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  R.** <tr><td>  B
2ffe0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
2fff0 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
30000 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
30010 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
30020 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
30030 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
30040 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
30050 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
30060 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
30070 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ^.**.** Note tha
30080 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
30090 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
300a0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
300b0 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
300c0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
300d0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
300e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
300f0 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
30100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30110 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
30120 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
30130 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
30140 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
30150 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
30160 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
30170 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
30180 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
30190 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
301a0 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
301b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
301c0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
301d0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
301e0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
301f0 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
30200 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
30210 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
30220 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
30230 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
30240 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
30250 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
30260 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
30270 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30280 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
30290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
302a0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
302b0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
302c0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
302d0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
302e0 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
302f0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
30300 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
30310 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
30320 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
30330 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
30340 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30350 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
30360 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
30370 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
30380 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
30390 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
303a0 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
303b0 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
303c0 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
303d0 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
303e0 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
303f0 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
30400 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
30410 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
30420 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
30430 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
30440 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
30450 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
30460 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
30470 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
30480 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
30490 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
304a0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
304b0 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
304c0 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
304d0 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
304e0 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
304f0 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
30500 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
30510 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
30520 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69   safest policy i
30530 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
30540 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
30550 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
30560 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
30570 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
30580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30590 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
305a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
305b0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
305c0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
305d0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
305e0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
305f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
30600 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
30610 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30620 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
30630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30640 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
30650 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
30660 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
30670 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
30680 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30690 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
306a0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
306b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
306c0 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
306d0 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
306e0 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
306f0 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
30700 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
30710 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
30720 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
30730 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
30740 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
30750 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
30760 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
30770 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
30780 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
30790 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
307a0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
307b0 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
307c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
307d0 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
307e0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
307f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
30800 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
30810 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
30820 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
30830 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
30840 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
30850 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
30860 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
30870 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
30880 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
30890 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
308a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
308b0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
308c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
308d0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
308e0 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
308f0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
30900 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
30910 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
30920 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65  atically.  Do <e
30930 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20  m>not</em> pass 
30940 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
30950 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
30960 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
30970 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
30980 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
30990 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
309a0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
309b0 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
309c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
309d0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
309e0 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
309f0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
30a00 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
30a10 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
30a20 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
30a30 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
30a40 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
30a50 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
30a60 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
30a70 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
30a80 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
30a90 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
30aa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
30ab0 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
30ac0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
30ad0 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
30ae0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
30af0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
30b00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30b10 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
30b20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
30b30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30b40 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
30b50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30b60 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
30b70 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
30b80 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
30b90 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
30ba0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
30bb0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
30bc0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
30bd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30be0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
30bf0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
30c00 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
30c10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30c20 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
30c30 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
30c40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
30c50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30c60 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
30c70 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30c80 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
30c90 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
30ca0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
30cb0 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
30cc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30cd0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
30ce0 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
30cf0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
30d00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
30d10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30d20 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
30d30 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
30d40 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55  Object.** DESTRU
30d50 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
30d60 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
30d70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
30d80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
30d90 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
30da0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30db0 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
30dc0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
30dd0 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
30de0 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
30df0 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
30e00 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
30e10 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
30e20 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
30e30 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
30e40 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
30e50 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
30e60 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
30e70 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
30e80 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
30e90 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
30ea0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
30eb0 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
30ec0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
30ed0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
30ee0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
30ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30f00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
30f10 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
30f20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
30f30 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
30f40 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
30f50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30f60 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
30f70 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
30f80 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
30f90 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
30fa0 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
30fb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30fc0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
30fd0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
30fe0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
30ff0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
31000 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
31010 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
31020 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
31030 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
31040 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
31050 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
31060 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
31070 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
31080 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
31090 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
310a0 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
310b0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
310c0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
310d0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
310e0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
310f0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
31100 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
31110 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
31120 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31130 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
31140 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
31150 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
31160 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
31170 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
31180 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
31190 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
311a0 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
311b0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
311c0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
311d0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
311e0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
311f0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
31200 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
31210 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
31220 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
31230 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
31240 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45  ent Object.** ME
31250 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
31260 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  mt.**.** The sql
31270 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
31280 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
31290 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
312a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
312b0 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
312c0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
312d0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
312e0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
312f0 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
31300 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
31310 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
31320 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
31330 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
31340 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
31350 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
31360 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
31370 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
31380 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
31390 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
313a0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
313b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
313c0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
313d0 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
313e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
313f0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
31400 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
31410 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
31420 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
31430 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
31440 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
31450 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
31460 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
31470 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
31480 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
31490 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
314a0 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
314b0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
314c0 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
314d0 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
314e0 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
314f0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
31500 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
31510 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
31520 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
31530 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
31540 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
31550 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31560 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
31570 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
31580 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
31590 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
315a0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
315b0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
315c0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
315d0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
315e0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
315f0 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
31600 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
31610 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
31620 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
31630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31640 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
31650 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
31660 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
31670 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31680 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
31690 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
316a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
316b0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
316c0 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
316d0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
316e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
316f0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
31700 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
31710 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
31720 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
31730 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
31740 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
31750 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
31760 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
31770 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
31780 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
31790 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
317a0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
317b0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
317c0 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
317d0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
317e0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
317f0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
31800 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
31810 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
31820 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
31830 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
31840 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
31850 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
31860 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
31870 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
31880 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
31890 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
318a0 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
318b0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
318c0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
318d0 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
318e0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
318f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
31900 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
31910 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
31920 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
31930 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
31940 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
31950 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
31960 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
31970 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
31980 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
31990 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
319a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
319b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
319c0 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
319d0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
319e0 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
319f0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
31a00 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
31a10 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
31a20 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
31a30 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
31a40 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
31a50 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
31a60 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
31a70 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
31a80 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
31a90 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
31aa0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
31ab0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
31ac0 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
31ad0 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
31ae0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
31af0 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
31b00 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
31b10 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
31b20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
31b30 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
31b40 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
31b50 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
31b60 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
31b70 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
31b80 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
31b90 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
31ba0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
31bb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
31bc0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
31bd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
31be0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
31bf0 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
31c00 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
31c10 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
31c20 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
31c30 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
31c40 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
31c50 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
31c60 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
31c70 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
31c80 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
31c90 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
31ca0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
31cb0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
31cc0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
31cd0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
31ce0 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
31cf0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
31d00 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
31d10 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
31d20 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
31d30 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
31d40 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
31d50 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
31d60 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
31d70 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
31d80 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
31d90 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
31da0 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20  should set this 
31db0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
31dc0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
31dd0 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   if the function
31de0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31df0 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c  invokes .** [sql
31e00 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31e10 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6le()] on an inp
31e20 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ut, or [SQLITE_U
31e30 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a  TF16BE] if the.*
31e40 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
31e50 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
31e60 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
31e70 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
31e80 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
31e90 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65  TF16] if [sqlite
31ea0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
31eb0 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53  ] is used, or [S
31ec0 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f  QLITE_UTF8].** o
31ed0 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20  therwise.  ^The 
31ee0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
31ef0 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
31f00 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
31f10 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66  es using.** diff
31f20 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20  erent preferred 
31f30 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20  text encodings, 
31f40 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69  with different i
31f50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
31f60 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64  or.** each encod
31f70 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  ing..** ^When mu
31f80 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
31f90 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
31fa0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
31fb0 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
31fc0 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
31fd0 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
31fe0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
31ff0 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
32000 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
32010 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
32020 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e  meter may option
32030 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74  ally be ORed wit
32040 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  h [SQLITE_DETERM
32050 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73  INISTIC].** to s
32060 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66  ignal that the f
32070 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77  unction will alw
32080 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
32090 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e  ame result given
320a0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70  .** the same inp
320b0 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e  uts within a sin
320c0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
320d0 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e  t.  Most SQL fun
320e0 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65  ctions are.** de
320f0 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
32100 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64  e built-in [rand
32110 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  om()] SQL functi
32120 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  on is an example
32130 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   of a.** functio
32140 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65  n that is not de
32150 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
32160 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70  e SQLite query p
32170 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74  lanner is able t
32180 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64  o.** perform add
32190 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61  itional optimiza
321a0 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69  tions on determi
321b0 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nistic functions
321c0 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74  , so use.** of t
321d0 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  he [SQLITE_DETER
321e0 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69  MINISTIC] flag i
321f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68  s recommended wh
32200 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a  ere possible..**
32210 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
32220 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
32230 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
32240 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
32250 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
32260 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
32270 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
32280 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
32290 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
322a0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
322b0 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
322c0 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
322d0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
322e0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
322f0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
32300 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
32310 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
32320 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
32330 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
32340 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
32350 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
32360 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
32370 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32380 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
32390 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
323a0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
323b0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
323c0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
323d0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
323e0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
323f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
32400 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
32410 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
32420 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
32430 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
32440 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
32450 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
32460 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
32470 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
32480 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
32490 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
324a0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
324b0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
324c0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
324d0 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
324e0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
324f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
32500 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
32510 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
32520 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
32530 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
32540 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
32550 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
32560 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
32570 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
32580 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
32590 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
325a0 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
325b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
325c0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
325d0 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
325e0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
325f0 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
32600 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
32610 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
32620 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
32630 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
32640 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
32650 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
32660 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
32670 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
32680 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
32690 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
326a0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
326b0 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
326c0 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
326d0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
326e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
326f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
32700 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
32710 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
32720 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
32730 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
32740 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
32750 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
32760 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
32770 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
32780 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
32790 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
327a0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
327b0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
327c0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
327d0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
327e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
327f0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
32800 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
32810 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
32820 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
32830 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
32840 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32850 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
32860 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
32870 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
32880 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
32890 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
328a0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
328b0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
328c0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
328d0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
328e0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
328f0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
32900 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
32910 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
32920 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
32930 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
32940 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
32950 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
32960 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
32970 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
32980 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
32990 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
329a0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
329b0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
329c0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
329d0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
329e0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
329f0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
32a00 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
32a10 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
32a20 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
32a30 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
32a40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32a50 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
32a60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32a70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
32a80 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
32a90 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
32aa0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
32ab0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
32ac0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
32ad0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
32ae0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
32af0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
32b00 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
32b10 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
32b20 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
32b30 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
32b40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
32b50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
32b60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
32b70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
32b80 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
32b90 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
32ba0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
32bb0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
32bc0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
32bd0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
32be0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
32bf0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
32c00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
32c10 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
32c20 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
32c30 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
32c40 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
32c50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32c60 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
32c70 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
32c80 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
32c90 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
32ca0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
32cb0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
32cc0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
32cd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32ce0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32cf0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32d00 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
32d10 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
32d20 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
32d30 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
32d40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
32d50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32d60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
32d70 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
32d80 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
32d90 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
32da0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
32db0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
32dc0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
32dd0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
32de0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
32df0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
32e00 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
32e10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32e20 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32e30 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
32e40 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
32e50 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
32e60 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
32e70 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
32e80 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
32e90 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
32ea0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
32eb0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
32ec0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
32ed0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
32ee0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
32ef0 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
32f00 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
32f10 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
32f20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a      1    /* IMP:
32f30 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a   R-37514-35566 *
32f40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
32f50 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
32f60 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30  2    /* IMP: R-0
32f70 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64  3371-37637 */.#d
32f80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
32f90 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20  16BE        3   
32fa0 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31   /* IMP: R-51971
32fb0 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e  -34154 */.#defin
32fc0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
32fd0 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
32fe0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
32ff0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
33000 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
33010 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44         5    /* D
33020 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65  eprecated */.#de
33030 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
33040 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
33050 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
33060 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
33070 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
33080 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c  REF: Function Fl
33090 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
330a0 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
330b0 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77   ORed together w
330c0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
330d0 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65  ITE_UTF8 | prefe
330e0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
330f0 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74  ng] as the fourt
33100 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
33110 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33120 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73  _function()], [s
33130 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33140 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  nction16()], or.
33150 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
33160 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
33170 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
33180 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
33190 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a  IC    0x800../*.
331a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
331b0 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
331c0 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
331d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
331e0 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
331f0 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
33200 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
33210 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
33220 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
33230 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
33240 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
33250 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
33260 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
33270 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
33280 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
33290 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
332a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
332b0 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f  To encourage pro
332c0 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69  grammers to avoi
332d0 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74  d.** these funct
332e0 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f  ions, we will no
332f0 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74  t explain what t
33300 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
33310 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
33320 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
33330 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
33340 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33350 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
33360 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
33370 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
33380 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
33390 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
333a0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
333b0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
333c0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
333d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
333e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
333f0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
33400 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
33410 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
33420 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
33430 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
33440 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
33450 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
33460 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
33470 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
33480 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
33490 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
334a0 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20  int),.          
334b0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
334c0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
334d0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
334e0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
334f0 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a  ing SQL Values.*
33500 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
33510 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68  3_value.**.** Th
33520 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
33530 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
33540 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
33550 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
33560 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
33570 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
33580 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
33590 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
335a0 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
335b0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
335c0 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  e.  .**.** The x
335d0 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
335e0 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
335f0 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
33600 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
33610 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
33620 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
33630 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
33640 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
33650 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
33660 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
33670 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
33680 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
33690 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
336a0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
336b0 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
336c0 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
336d0 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
336e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
336f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
33700 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
33710 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
33720 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
33730 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
33740 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
33750 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
33760 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
33770 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
33780 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
33790 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
337a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
337b0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
337c0 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
337d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
337e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
337f0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
33800 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
33810 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
33820 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33830 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
33840 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
33850 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
33860 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
33870 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
33880 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
33890 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
338a0 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
338b0 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20  cept that these 
338c0 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
338d0 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
338e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
338f0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
33900 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
33910 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
33920 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
33930 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
33940 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
33950 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
33960 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
33970 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
33980 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
33990 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
339a0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
339b0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
339c0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
339d0 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
339e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
339f0 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
33a00 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
33a10 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
33a20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
33a30 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
33a40 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
33a50 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
33a60 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
33a70 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
33a80 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
33a90 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
33aa0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
33ab0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
33ac0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
33ad0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
33ae0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
33af0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
33b00 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
33b10 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
33b20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
33b30 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
33b40 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
33b50 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
33b60 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
33b70 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
33b80 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
33b90 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
33ba0 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
33bb0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
33bc0 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
33bd0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
33be0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
33bf0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
33c00 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
33c10 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
33c20 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
33c30 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
33c40 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
33c50 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
33c60 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
33c70 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
33c80 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
33c90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33ca0 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
33cb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33cc0 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
33cd0 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
33ce0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
33cf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
33d00 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
33d10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
33d20 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
33d30 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
33d40 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
33d50 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
33d60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
33d70 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
33d80 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
33d90 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
33da0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
33db0 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
33dc0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
33dd0 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
33de0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
33df0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
33e00 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33e10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
33e20 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
33e30 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
33e40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
33e50 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
33e60 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
33e70 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
33e80 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
33e90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
33ea0 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
33eb0 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
33ec0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
33ed0 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
33ee0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
33ef0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
33f00 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
33f10 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
33f20 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
33f30 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
33f40 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
33f50 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
33f60 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
33f70 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
33f80 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
33f90 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
33fa0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
33fb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33fc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
33fd0 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
33fe0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
33ff0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
34000 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
34010 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
34020 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e  API3REF: Copy An
34030 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65  d Free SQL Value
34040 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
34050 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
34060 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
34070 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
34080 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
34090 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
340a0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
340b0 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73  ct D and returns
340c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
340d0 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b  at copy.  ^The [
340e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72  sqlite3_value] r
340f0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20  eturned.** is a 
34100 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
34110 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34120 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70   even if the inp
34130 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54  ut is not..** ^T
34140 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
34150 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63  _dup(V) interfac
34160 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
34170 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69  f V is NULL or i
34180 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
34190 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a  location fails..
341a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
341b0 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
341c0 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73   interface frees
341d0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   an [sqlite3_val
341e0 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72  ue] object.** pr
341f0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
34200 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
34210 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e  value_dup()].  ^
34220 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70  If V is a NULL p
34230 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73  ointer.** then s
34240 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
34250 65 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65  e(V) is a harmle
34260 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
34270 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
34280 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
34290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
342a0 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  p(const sqlite3_
342b0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
342c0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
342d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
342e0 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  free(sqlite3_val
342f0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
34300 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
34310 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
34320 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48   Context.** METH
34330 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
34340 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
34350 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
34360 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
34370 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
34380 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
34390 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
343a0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
343b0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
343c0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
343d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
343e0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
343f0 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
34400 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
34410 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
34420 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
34430 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
34440 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
34450 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
34460 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
34470 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
34480 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
34490 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
344a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
344b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
344c0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
344d0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
344e0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
344f0 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
34500 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
34510 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
34520 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34530 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
34540 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
34550 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
34560 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
34570 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
34580 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
34590 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
345a0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
345b0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
345c0 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
345d0 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
345e0 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
345f0 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
34600 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
34610 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
34620 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
34630 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
34640 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
34650 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
34660 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
34670 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
34680 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
34690 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
346a0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
346b0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
346c0 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
346d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
346e0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
346f0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
34700 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
34710 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72  ter .** when fir
34720 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69  st called if N i
34730 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
34740 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
34750 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
34760 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
34770 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
34780 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
34790 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
347a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
347b0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
347c0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
347d0 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
347e0 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
347f0 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
34800 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
34810 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
34820 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
34830 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
34840 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
34850 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
34860 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
34870 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
34880 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
34890 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
348a0 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65  n.)^  Within the
348b0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
348c0 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72  , it is customar
348d0 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20  y to set.** N=0 
348e0 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  in calls to sqli
348f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34900 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68  ntext(C,N) so th
34910 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c  at no .** pointl
34920 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ess memory alloc
34930 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a  ations occur..**
34940 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
34950 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
34960 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
34970 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
34980 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34990 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
349a0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
349b0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
349c0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
349d0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
349e0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
349f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
34a00 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
34a10 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
34a20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
34a30 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
34a40 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
34a50 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
34a60 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
34a70 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
34a80 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
34a90 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
34aa0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
34ab0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
34ac0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
34ad0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
34ae0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
34af0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
34b00 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34b10 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
34b20 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
34b30 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
34b40 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
34b50 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
34b60 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34b70 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
34b80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
34b90 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
34ba0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
34bb0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
34bc0 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
34bd0 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
34be0 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
34bf0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
34c00 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
34c10 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
34c20 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
34c30 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
34c40 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
34c50 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
34c60 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
34c70 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
34c80 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
34c90 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
34ca0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
34cb0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
34cc0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
34cd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34ce0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34cf0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
34d00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
34d10 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
34d20 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
34d30 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
34d40 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
34d50 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
34d60 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34d70 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e  _context.**.** ^
34d80 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
34d90 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
34da0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34db0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
34dc0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
34dd0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
34de0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
34df0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
34e00 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
34e10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
34e20 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
34e30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34e40 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
34e50 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
34e60 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
34e70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
34e80 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
34e90 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
34ea0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
34eb0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
34ec0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
34ed0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
34ee0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
34ef0 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  a.** METHOD: sql
34f00 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
34f10 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
34f20 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
34f30 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65  y (non-aggregate
34f40 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  ) SQL functions 
34f50 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
34f60 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
34f70 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
34f80 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
34f90 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
34fa0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
34fb0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
34fc0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
34fd0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
34fe0 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
34ff0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
35000 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
35010 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
35020 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e  e preserved.  An
35030 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77   example.** of w
35040 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20  here this might 
35050 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20  be useful is in 
35060 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
35070 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a  sion matching.**
35080 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
35090 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
350a0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
350b0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
350c0 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
350d0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
350e0 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65  d with the patte
350f0 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20  rn string.  .** 
35100 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20  Then as long as 
35110 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
35120 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73  ng remains the s
35130 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70  ame,.** the comp
35140 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
35150 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
35160 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
35170 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
35180 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
35190 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ction..**.** ^Th
351a0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
351b0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
351c0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
351d0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
351e0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
351f0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
35200 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
35210 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
35220 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
35230 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
35240 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35250 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
35260 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61  there is no meta
35270 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
35280 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63  ed with the func
35290 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74  tion argument, t
352a0 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  his sqlite3_get_
352b0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
352c0 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  ace.** returns a
352d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
352e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
352f0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
35300 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65  N,P,X) interface
35310 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61   saves P as meta
35320 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
35330 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
35340 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35350 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35360 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a  n.  ^Subsequent.
35370 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
35380 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
35390 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72  C,N) return P fr
353a0 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  om the most rece
353b0 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  nt.** sqlite3_se
353c0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
353d0 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d  X) call if the m
353e0 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c  etadata is still
353f0 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c   valid or.** NUL
35400 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  L if the metadat
35410 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61  a has been disca
35420 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20  rded..** ^After 
35430 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  each call to sql
35440 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35450 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20  (C,N,P,X) where 
35460 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  X is not NULL,.*
35470 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  * SQLite will in
35480 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
35490 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77  tor function X w
354a0 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20  ith parameter P 
354b0 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c  exactly.** once,
354c0 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61   when the metada
354d0 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e  ta is discarded.
354e0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
354f0 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68  ee to discard th
35500 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e  e metadata at an
35510 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e  y time, includin
35520 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  g: <ul>.** <li> 
35530 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
35540 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
35550 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
35560 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  s, or.** <li> wh
35570 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
35580 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
35590 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
355a0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
355b0 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65  *      SQL state
355c0 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ment, or.** <li>
355d0 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65   when sqlite3_se
355e0 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69  t_auxdata() is i
355f0 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20  nvoked again on 
35600 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
35610 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64  er, or.** <li> d
35620 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  uring the origin
35630 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  al sqlite3_set_a
35640 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68  uxdata() call wh
35650 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20  en a memory .** 
35660 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20       allocation 
35670 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f  error occurs. </
35680 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ul>)^.**.** Note
35690 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74   the last bullet
356a0 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20   in particular. 
356b0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
356c0 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33  X in .** sqlite3
356d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
356e0 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63  ,P,X) might be c
356f0 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  alled immediatel
35700 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a  y, before the.**
35710 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35720 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
35730 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20   even returns.  
35740 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65  Hence sqlite3_se
35750 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73  t_auxdata().** s
35760 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20  hould be called 
35770 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20  near the end of 
35780 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
35790 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20  lementation and 
357a0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
357b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
357c0 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61  hould not make a
357d0 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65  ny use of P afte
357e0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  r.** sqlite3_set
357f0 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62  _auxdata() has b
35800 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a  een called..**.*
35810 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
35820 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
35830 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
35840 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
35850 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  r.** function pa
35860 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
35870 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63  e compile-time c
35880 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64  onstants, includ
35890 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  ing literal.** v
358a0 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
358b0 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65  eters] and expre
358c0 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20  ssions composed 
358d0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e  from the same.)^
358e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
358f0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
35900 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
35910 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
35920 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
35930 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
35940 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
35950 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
35960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35970 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
35980 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35990 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
359a0 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
359b0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
359c0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
359d0 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
359e0 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
359f0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
35a00 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
35a10 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
35a20 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
35a30 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
35a40 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
35a50 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
35a60 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
35a70 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
35a80 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
35a90 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
35aa0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
35ab0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
35ac0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
35ad0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
35ae0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
35af0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
35b00 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
35b10 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
35b20 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
35b30 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
35b40 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
35b50 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
35b60 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
35b70 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
35b80 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
35b90 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
35ba0 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
35bb0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
35bc0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
35bd0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
35be0 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
35bf0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
35c00 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
35c10 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
35c20 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
35c30 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
35c40 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
35c50 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
35c60 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
35c70 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
35c80 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
35c90 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
35ca0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
35cb0 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
35cc0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
35cd0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
35ce0 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
35cf0 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
35d00 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
35d10 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
35d20 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54  _context.**.** T
35d30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
35d40 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
35d50 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
35d60 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
35d70 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
35d80 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
35d90 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
35da0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35db0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
35dc0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35dd0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
35de0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
35df0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
35e00 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
35e10 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
35e20 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
35e30 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
35e40 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
35e50 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
35e60 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
35e70 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
35e80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35e90 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
35ea0 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
35eb0 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
35ec0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
35ed0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
35ee0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35ef0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
35f00 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
35f10 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
35f20 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
35f30 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35f40 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
35f50 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
35f60 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
35f70 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
35f80 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
35f90 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
35fa0 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
35fb0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
35fc0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
35fd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
35fe0 65 72 6f 62 6c 6f 62 28 29 20 61 6e 64 20 7a 65  eroblob() and ze
35ff0 72 6f 62 6c 6f 62 36 34 28 29 20 69 6e 74 65 72  roblob64() inter
36000 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
36010 73 75 6c 74 20 0a 2a 2a 20 6f 66 20 74 68 65 20  sult .** of the 
36020 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36030 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
36040 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
36050 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
36060 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
36070 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
36080 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
36090 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
360a0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
360b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
360c0 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
360d0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
360e0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
360f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36100 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36110 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
36120 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
36130 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
36140 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
36150 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36160 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
36170 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36180 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
36190 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
361a0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
361b0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
361c0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
361d0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
361e0 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
361f0 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
36200 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
36210 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
36220 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
36230 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36240 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
36250 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
36260 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
36270 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
36280 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
36290 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
362a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
362b0 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
362c0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
362d0 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
362e0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
362f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
36300 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
36310 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
36320 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
36330 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
36340 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36350 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
36360 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36370 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
36380 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
36390 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
363a0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
363b0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
363c0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
363d0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
363e0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
363f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
36400 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
36410 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
36420 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
36430 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
36440 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
36450 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
36460 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
36470 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
36480 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
36490 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
364a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
364b0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
364c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
364d0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
364e0 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
364f0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
36500 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
36510 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
36520 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
36530 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
36540 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
36550 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
36560 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
36570 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
36580 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
36590 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
365a0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
365b0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
365c0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
365d0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
365e0 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
365f0 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
36600 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
36610 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
36620 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
36630 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
36640 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
36650 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
36660 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
36670 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
36680 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
36690 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
366a0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
366b0 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
366c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
366d0 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  or_toobig() inte
366e0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
366f0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
36700 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
36710 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
36720 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
36730 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
36740 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
36750 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36760 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ror_nomem() inte
36770 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
36780 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
36790 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
367a0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
367b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
367c0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
367d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
367e0 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
367f0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
36800 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
36810 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36820 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36830 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
36840 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
36850 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
36860 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
36870 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36880 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
36890 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
368a0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
368b0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
368c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
368d0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
368e0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
368f0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
36900 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
36910 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
36920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36930 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
36940 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36950 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
36960 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36970 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36980 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
36990 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
369a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
369b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
369c0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
369d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
369e0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
369f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36a00 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
36a10 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
36a20 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
36a30 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36a40 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36a50 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
36a60 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
36a70 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
36a80 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
36a90 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
36aa0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
36ab0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
36ac0 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
36ad0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65  ctively..** ^The
36ae0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36af0 74 65 78 74 36 34 28 29 20 69 6e 74 65 72 66 61  text64() interfa
36b00 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
36b10 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a  rn value of an.*
36b20 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  * application-de
36b30 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
36b40 6f 20 62 65 20 61 20 74 65 78 74 20 73 74 72 69  o be a text stri
36b50 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e  ng in an encodin
36b60 67 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62  g.** specified b
36b70 79 20 74 68 65 20 66 69 66 74 68 20 28 61 6e 64  y the fifth (and
36b80 20 6c 61 73 74 29 20 70 61 72 61 6d 65 74 65 72   last) parameter
36b90 2c 20 77 68 69 63 68 20 6d 75 73 74 20 62 65 20  , which must be 
36ba0 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54  one.** of [SQLIT
36bb0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
36bc0 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
36bd0 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
36be0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a  QLITE_UTF16LE]..
36bf0 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
36c00 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
36c10 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
36c20 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
36c30 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
36c40 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
36c50 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
36c60 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
36c70 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
36c80 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
36c90 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
36ca0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
36cb0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
36cc0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
36cd0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
36ce0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
36cf0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
36d00 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
36d10 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
36d20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
36d30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36d40 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
36d50 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
36d60 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
36d70 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
36d80 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
36d90 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
36da0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
36db0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
36dc0 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
36dd0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
36de0 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
36df0 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
36e00 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
36e10 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
36e20 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
36e30 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
36e40 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
36e50 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
36e60 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
36e70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
36e80 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
36e90 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
36ea0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
36eb0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
36ec0 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
36ed0 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
36ee0 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
36ef0 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
36f00 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
36f10 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
36f20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
36f30 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
36f40 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
36f50 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
36f60 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
36f70 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
36f80 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
36f90 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
36fa0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
36fb0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
36fc0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
36fd0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
36fe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36ff0 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
37000 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
37010 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
37020 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
37030 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
37040 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
37050 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
37060 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
37070 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
37080 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
37090 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
370a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
370b0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
370c0 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
370d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
370e0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
370f0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
37100 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
37110 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
37120 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
37130 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
37140 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
37150 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
37160 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
37170 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
37180 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
37190 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
371a0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
371b0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
371c0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
371d0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
371e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
371f0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
37200 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
37210 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
37220 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
37230 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
37240 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
37250 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
37260 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
37270 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
37280 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
37290 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
372a0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
372b0 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
372c0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
372d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
372e0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
372f0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
37300 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
37310 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37320 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37330 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
37340 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
37350 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37360 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
37370 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
37380 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
37390 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
373a0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
373b0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
373c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
373d0 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
373e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
373f0 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
37400 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
37410 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
37420 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
37430 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
37440 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
37450 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
37460 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
37470 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
37480 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
37490 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
374a0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
374b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
374c0 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
374d0 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
374e0 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
374f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37500 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
37510 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
37520 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
37530 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
37540 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
37550 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
37560 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
37570 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
37580 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
37590 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
375a0 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
375b0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
375c0 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
375d0 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
375e0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
375f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37600 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
37610 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
37620 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
37630 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
37640 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37650 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  lt_blob64(sqlite
37660 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74  3_context*,const
37670 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20   void*,.        
37680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37690 20 20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36     sqlite3_uint6
376a0 34 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  4,void(*)(void*)
376b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
376c0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
376d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
376e0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
376f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37700 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
37710 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
37720 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
37730 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37740 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
37750 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
37760 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
37770 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37780 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
37790 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
377a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
377b0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
377c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
377d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
377e0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
377f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37800 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
37810 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
37820 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37830 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
37840 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
37850 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37860 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
37870 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37880 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
37890 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
378a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
378b0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
378c0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
378d0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
378e0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
378f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37900 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
37910 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37920 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
37930 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
37940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37950 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
37960 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
37970 6e 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73  ncoding);.void s
37980 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37990 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
379a0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
379b0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
379c0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
379d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
379e0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
379f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37a00 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
37a10 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
37a20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37a30 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
37a40 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37a50 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
37a60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
37a70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37a80 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
37a90 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
37aa0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
37ab0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
37ac0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
37ad0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
37ae0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 75  int sqlite3_resu
37af0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  lt_zeroblob64(sq
37b00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37b10 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 6e  sqlite3_uint64 n
37b20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37b30 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
37b40 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
37b50 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
37b60 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
37b70 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64  se functions add
37b80 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64  , remove, or mod
37b90 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e  ify a [collation
37ba0 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  ] associated.** 
37bb0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
37bc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
37bd0 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
37be0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
37bf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
37c00 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
37c10 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
37c20 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
37c30 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37c40 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
37c50 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37c60 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
37c70 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
37c80 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
37c90 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  er for sqlite3_c
37ca0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
37cb0 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  6()..** ^Collati
37cc0 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f  on names that co
37cd0 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f  mpare equal acco
37ce0 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65  rding to [sqlite
37cf0 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72  3_strnicmp()] ar
37d00 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
37d10 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e  to be the same n
37d20 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ame..**.** ^(The
37d30 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
37d40 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20  (eTextRep) must 
37d50 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
37d60 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e  nstants:.** <ul>
37d70 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
37d80 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _UTF8],.** <li> 
37d90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
37da0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
37db0 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c  E_UTF16BE],.** <
37dc0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
37dd0 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  6], or.** <li> [
37de0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
37df0 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29  GNED]..** </ul>)
37e00 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52  ^.** ^The eTextR
37e10 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65  ep argument dete
37e20 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64  rmines the encod
37e30 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70  ing of strings p
37e40 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  assed.** to the 
37e50 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37e60 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61  on callback, xCa
37e70 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
37e80 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61  [SQLITE_UTF16] a
37e90 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  nd [SQLITE_UTF16
37ea0 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73  _ALIGNED] values
37eb0 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a   for eTextRep.**
37ec0 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74   force strings t
37ed0 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20  o be UTF16 with 
37ee0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
37ef0 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  r..** ^The [SQLI
37f00 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
37f10 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78  ] value for eTex
37f20 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69  tRep forces stri
37f30 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20  ngs to begin.** 
37f40 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20  on an even byte 
37f50 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e  address..**.** ^
37f60 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
37f70 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e  ent, pArg, is an
37f80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
37f90 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
37fa0 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
37fb0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
37fc0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
37fd0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37fe0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
37ff0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
38000 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
38010 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
38020 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
38030 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
38040 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
38050 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
38060 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
38070 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
38080 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
38090 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
380a0 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
380b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
380c0 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
380d0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
380e0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
380f0 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
38100 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
38110 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
38120 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
38130 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
38140 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
38150 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
38160 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
38170 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
38180 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
38190 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
381a0 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
381b0 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
381c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
381d0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
381e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
381f0 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
38200 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
38210 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
38220 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
38230 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
38240 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
38250 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
38260 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
38270 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
38280 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
38290 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
382a0 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
382b0 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
382c0 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
382d0 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
382e0 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
382f0 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
38300 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
38310 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
38320 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
38330 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
38340 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
38350 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
38360 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
38370 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
38380 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
38390 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
383a0 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  e registered.** 
383b0 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c  to the same coll
383c0 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e  ation name (usin
383d0 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  g different eTex
383e0 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65  tRep values) the
383f0 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69  n all.** must gi
38400 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  ve an equivalent
38410 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76   answer when inv
38420 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61  oked with equiva
38430 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  lent strings..**
38440 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
38450 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65  unction must obe
38460 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
38470 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61  properties for a
38480 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c  ll.** strings A,
38490 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a   B, and C:.**.**
384a0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
384b0 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e   A==B then B==A.
384c0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
384d0 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41   and B==C then A
384e0 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==C..** <li> If 
384f0 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74  A&lt;B THEN B&gt
38500 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ;A..** <li> If A
38510 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43  &lt;B and B&lt;C
38520 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a   then A&lt;C..**
38530 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ol>.**.** If 
38540 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  a collating func
38550 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f  tion fails any o
38560 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73  f the above cons
38570 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74  traints and that
38580 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  .** collating fu
38590 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73  nction is  regis
385a0 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20  tered and used, 
385b0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
385c0 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69  r of SQLite.** i
385d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
385e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
385f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38600 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
38610 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38620 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77  collation().** w
38630 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e  ith the addition
38640 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72   that the xDestr
38650 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  oy callback is i
38660 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77  nvoked on pArg w
38670 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  hen.** the colla
38680 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
38690 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f   deleted..** ^Co
386a0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
386b0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68  s are deleted wh
386c0 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
386d0 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a  ridden by later.
386e0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ** calls to the 
386f0 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
38700 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
38710 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74  when the.** [dat
38720 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38730 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  ] is closed usin
38740 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
38750 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ()]..**.** ^The 
38760 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
38770 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20  k is <u>not</u> 
38780 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a  called if the .*
38790 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
387a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
387b0 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20  function fails. 
387c0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
387d0 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  at invoke.** sql
387e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
387f0 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20  ation_v2() with 
38800 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
38810 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  r