/ Hex Artifact Content
Login

Artifact 3932a4505c6b7594f53247c3e14222701b0e0e70:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  eter of.** sqlit
39c0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
39d0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
39e0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
39f0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3a00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3a10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3a30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3a40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3a50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3a60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3a70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3a80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3a90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3aa0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3ab0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3ac0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3ad0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3af0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3b00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3b10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3b20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3b30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3b40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3b50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3b60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3b70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3b80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3b90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3ba0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3bb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3bc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3bd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3be0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3bf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3c10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3c20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3c30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3c40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3c50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3c60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3c70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3c80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3c90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3ca0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3cb0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3cc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3cd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3ce0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3cf0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3d20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3d50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3d60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3d70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3d80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3d90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3da0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3db0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3dc0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3dd0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3de0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3df0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3e00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3e10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3e20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3e30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3e40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3e50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3e60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3e70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3e80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3e90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3ea0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3eb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3ec0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ed0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3ee0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
3ef0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
3f00: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3f10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3f20: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
3f30: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
3f40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
3f50: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3f60: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
3f70: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
3f80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3f90: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3fa0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3fb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3fc0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3fd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fe0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ff0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4000: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4010: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4020: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4030: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4040: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4050: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4060: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4070: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
4080: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
4090: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
40a0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
40d0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
40e0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
40f0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4120: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4130: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4140: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4150: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4160: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4170: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41a0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
41b0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
41c0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
41f0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4200: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4210: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4220: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4230: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4240: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4250: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4260: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4270: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
4280: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
4290: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
42a0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
42b0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
42c0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
42d0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
42e0: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
42f0: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4300: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4310: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4320: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4330: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4340: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4350: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4360: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4370: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4380: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4390: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43a0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
43b0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
43c0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
43d0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
43e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
43f0: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4400: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4410: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4420: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4430: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4440: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4450: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4470: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4480: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4490: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44a0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
44b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
44c0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
44d0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
44e0: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
44f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4500: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4510: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4520: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4530: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4540: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4550: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4560: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4580: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4590: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45a0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
45b0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
45c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
45d0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
45e0: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
45f0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4600: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4620: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4630: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4640: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4650: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4660: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4670: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4680: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4690: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46b0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
46c0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
46d0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
46e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
46f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4700: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4710: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4720: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4730: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4760: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4770: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4780: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4790: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47a0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
47b0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
47c0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
47d0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
47e0: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
47f0: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4810: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4820: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4830: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4840: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4850: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4860: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4870: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4880: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48a0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
48b0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
48c0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
48d0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
48e0: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
48f0: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4900: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4920: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4930: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4940: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4960: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4970: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4980: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4990: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
49b0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
49c0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
49d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
49e0: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
49f0: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a00: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a10: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a20: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a30: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a40: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4a50: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4a60: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a70: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a80: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a90: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4aa0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4ab0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4ad0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4ae0: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4af0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b10: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4b20: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4b30: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b50: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4b60: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4b70: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4b80: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4ba0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4bb0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4bc0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4bd0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4be0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4bf0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4c00: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4c10: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4c20: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4c30: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4c40: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4c50: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4c60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4c70: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4c80: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4c90: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4ca0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4cb0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4cc0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4cd0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4ce0: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4cf0: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4d00: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4d10: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4d20: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4d30: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4d40: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4d50: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4d60: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4d70: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4d80: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4d90: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4da0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
4db0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
4dc0: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
4dd0: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
4de0: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
4df0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
4e00: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
4e10: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
4e20: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
4e30: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
4e40: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4e50: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
4e60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4e70: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
4e80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4e90: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4ea0: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
4eb0: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
4ec0: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
4ed0: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
4ee0: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
4ef0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
4f00: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
4f10: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
4f20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4f30: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f50: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4f60: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4f70: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4f90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fa0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
4fb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
4fd0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4fe0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
4ff0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5000: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5010: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5020: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5030: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5040: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5050: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5060: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
5070: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5080: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
5090: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50a0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
50b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50c0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
50d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50e0: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
50f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5100: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5120: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5130: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5140: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5160: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
5170: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5180: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
5190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51a0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
51b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51c0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5220: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5230: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5240: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5260: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
5270: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
5280: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
5290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52a0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
52b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52c0: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
52d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52e0: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
52f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5300: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5320: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5330: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5340: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
5350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5360: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
5370: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5380: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
5390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53a0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
53b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53c0: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
53d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53e0: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
53f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5400: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5420: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5430: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5440: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
5450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5460: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
5470: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5480: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
5490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54a0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
54b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54c0: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
54d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54e0: 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20  ERR_MMAP        
54f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5500: 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23  ERR | (24<<8)).#
5510: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5520: 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20  ERR_GETTEMPPATH 
5530: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5540: 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23  ERR | (25<<8)).#
5550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5560: 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  ERR_CONVPATH    
5570: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5580: 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23  ERR | (26<<8)).#
5590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55a0: 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20  ERR_VNODE       
55b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
55c0: 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23  ERR | (27<<8)).#
55d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55e0: 45 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20  ERR_AUTH        
55f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5600: 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23  ERR | (28<<8)).#
5610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5620: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5630: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5640: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
5650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5660: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
5670: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5680: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
5690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56a0: 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20  BUSY_SNAPSHOT   
56b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56c0: 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29  BUSY   |  (2<<8)
56d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56e0: 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50  _CANTOPEN_NOTEMP
56f0: 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45  DIR      (SQLITE
5700: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c  _CANTOPEN | (1<<
5710: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5720: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49  TE_CANTOPEN_ISDI
5730: 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  R          (SQLI
5740: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32  TE_CANTOPEN | (2
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5760: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55  LITE_CANTOPEN_FU
5770: 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51  LLPATH       (SQ
5780: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5790: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
57a0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57b0: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28  CONVPATH       (
57c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
57d0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
57e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
57f0: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20  _VTAB           
5800: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5810: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5830: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5840: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5850: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5870: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5880: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5890: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
58a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
58b0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
58c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
58d0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
58e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58f0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5900: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5910: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5920: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5930: 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b  E_ABORT_ROLLBACK
5940: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5950: 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29  E_ABORT | (2<<8)
5960: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43  _CONSTRAINT_CHEC
5980: 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  K        (SQLITE
5990: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31  _CONSTRAINT | (1
59a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59c0: 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51  COMMITHOOK   (SQ
59d0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59e0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
59f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a00: 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20  INT_FOREIGNKEY  
5a10: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a20: 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  INT | (3<<8)).#d
5a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a40: 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e  STRAINT_FUNCTION
5a50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a60: 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29  STRAINT | (4<<8)
5a70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e  _CONSTRAINT_NOTN
5a90: 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45  ULL      (SQLITE
5aa0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35  _CONSTRAINT | (5
5ab0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5ad0: 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51  PRIMARYKEY   (SQ
5ae0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5af0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
5b00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5b10: 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20  INT_TRIGGER     
5b20: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5b30: 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  INT | (7<<8)).#d
5b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5b50: 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20  STRAINT_UNIQUE  
5b60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b70: 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29  STRAINT | (8<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42  _CONSTRAINT_VTAB
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39  _CONSTRAINT | (9
5bc0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5bd0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5be0: 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51  ROWID        (SQ
5bf0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5c00: 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e  |(10<<8)).#defin
5c10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c20: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
5c30: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c40: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5c50: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c60: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
5c70: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c80: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5c90: 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47  e SQLITE_WARNING
5ca0: 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20  _AUTOINDEX      
5cb0: 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47   (SQLITE_WARNING
5cc0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5cd0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55  ne SQLITE_AUTH_U
5ce0: 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20  SER             
5cf0: 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c    (SQLITE_AUTH |
5d00: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
5d10: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
5d20: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
5d30: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
5d40: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5d50: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
5d60: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
5d70: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
5d80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
5d90: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
5da0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
5db0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5dc0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
5dd0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
5de0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5df0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5e00: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5e10: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
5e20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5e40: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
5e50: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
5e60: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5e70: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5e90: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5ea0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5eb0: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5ec0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5ed0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5ee0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5ef0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5f00: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
5f10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5f20: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
5f30: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
5f40: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
5f50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5f60: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5f70: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5f80: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5f90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5fa0: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
5fb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5fc0: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
5fd0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5fe0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5ff0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
6000: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6010: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
6020: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6030: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6040: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6050: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6060: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6070: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6080: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6090: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
60a0: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
60b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
60c0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
60d0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
60e0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
60f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6100: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
6110: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
6120: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
6130: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6140: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6150: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6160: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6170: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6180: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6190: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
61a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
61b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
61c0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
61d0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
61e0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
61f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6200: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
6210: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
6220: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6230: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6240: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6250: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6260: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6270: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6280: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6290: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62a0: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
62b0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
62c0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
62d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
62e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62f0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
6300: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
6310: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6320: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6330: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6340: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6350: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6360: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6370: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6380: 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54  TE_OPEN_FILEPROT
6390: 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20  ECTION_MASK     
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63b0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
63c0: 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72  700000../* Reser
63d0: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
63e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
63f0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
6400: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
6410: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
6420: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
6430: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6440: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6450: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6460: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6470: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6480: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6490: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
64a0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
64b0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
64c0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
64d0: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
64e0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
64f0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6500: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6510: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6520: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
6530: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6540: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6550: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6560: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6570: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6580: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6590: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
65a0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
65b0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
65c0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
65d0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
65e0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
65f0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6600: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6610: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6620: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
6630: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6640: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6650: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6660: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6670: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6680: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6690: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
66a0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
66b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
66c0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
66d0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
66e0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
66f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6700: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6710: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6720: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
6730: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6740: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6750: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6760: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6770: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6780: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6790: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
67a0: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
67b0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
67c0: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
67d0: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
67e0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
67f0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6800: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6810: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6820: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
6830: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6840: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6850: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6860: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6870: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6880: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
68a0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
68b0: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
68c0: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
68d0: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
68e0: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
68f0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
6900: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6910: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6920: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6930: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6940: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6950: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6960: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6970: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6980: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6990: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69a0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
69b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
69c0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
69d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
69e0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
69f0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6a00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a10: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6a20: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a40: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6a50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a60: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6a70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a80: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6a90: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ab0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6ac0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6ad0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6ae0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6af0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6b00: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b20: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6b30: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b40: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6b50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6b60: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6b70: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6b80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b90: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6ba0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6bb0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6bc0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6bd0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6be0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6bf0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6c00: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6c10: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6c20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c30: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6c40: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6c50: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6c60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6c70: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6c80: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6c90: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6ca0: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6cb0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6cc0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6cd0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6ce0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6cf0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6d00: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6d10: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6d20: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6d30: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6d40: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6d50: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6d60: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6d70: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6d90: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6da0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6db0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6dc0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6dd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6de0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6df0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6e00: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6e10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6e20: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6e30: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6e40: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6e50: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6e60: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6e70: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6e80: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6e90: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6ea0: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6eb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6ec0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6ed0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6ee0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6ef0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6f00: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6f10: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6f20: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6f30: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6f40: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6f50: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
6f60: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
6f70: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
6f80: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6f90: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
6fa0: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
6fb0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
6fc0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
6fd0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6fe0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
6ff0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
7000: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
7010: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
7020: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
7030: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
7040: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7050: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7060: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7070: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7080: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7090: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
70a0: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
70b0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
70c0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
70d0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
70e0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
70f0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
7100: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
7110: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7120: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
7130: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7140: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7150: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7160: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7170: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7180: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7190: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
71a0: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
71b0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
71c0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
71d0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
71e0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
71f0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
7200: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
7210: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7220: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
7230: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7240: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7250: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7260: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7270: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7280: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7290: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
72a0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
72b0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
72c0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
72d0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
72e0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
72f0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
7300: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
7310: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7320: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
7330: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7340: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7350: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7360: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7370: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7380: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7390: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
73a0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
73b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
73c0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
73d0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
73e0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
73f0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
7400: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
7410: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7420: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
7430: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7440: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7450: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7460: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7470: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7480: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7490: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
74a0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
74b0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
74c0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
74d0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
74e0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
74f0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7500: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7510: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7520: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
7530: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7540: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7550: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7560: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7570: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7580: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7590: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
75a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
75b0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
75c0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
75d0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
75e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
75f0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
7600: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7610: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7620: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
7630: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7640: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7650: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7670: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7680: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7690: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
76a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
76b0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
76c0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
76d0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
76e0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
76f0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7700: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7710: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7720: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
7730: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7740: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7750: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7760: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7770: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7780: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7790: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
77a0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
77b0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
77c0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
77d0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
77e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
77f0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
7800: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7810: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7820: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7830: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7840: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7850: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7860: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7870: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7880: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7890: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
78a0: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
78b0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
78c0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
78d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
78e0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
78f0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
7900: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7910: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7920: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
7930: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7940: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7950: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7960: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7970: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7980: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7990: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
79a0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
79b0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
79c0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
79d0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
79e0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
79f0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7a00: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7a10: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7a20: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
7a30: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
7a40: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7a50: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7a60: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7a70: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7a80: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7a90: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7aa0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7ab0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7ac0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7ad0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7ae0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7af0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7b00: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7b10: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7b20: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7b30: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7b40: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7b50: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7b60: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7b70: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7b80: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7b90: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7ba0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7bb0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7bc0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7bd0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7be0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7bf0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7c00: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7c10: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7c20: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7c30: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7c40: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7c50: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7c60: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7c70: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7c80: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7c90: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7ca0: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7cb0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7cc0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7cd0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7ce0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7cf0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7d00: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7d10: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7d20: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7d30: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7d40: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7d50: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7d60: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7d70: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7d80: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7d90: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7da0: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7db0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7dc0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7dd0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7de0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7df0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7e00: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7e10: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7e20: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7e30: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7e40: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7e50: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7e60: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7e70: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7e80: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7e90: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7ea0: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7eb0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7ec0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7ed0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7ee0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7ef0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7f00: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7f10: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7f20: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7f30: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7f40: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7f50: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7f60: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7f70: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7f80: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7f90: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7fa0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7fb0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7fc0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7fd0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7fe0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7ff0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
8000: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
8010: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8020: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8030: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8040: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8050: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8060: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8070: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8080: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8090: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
80a0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
80b0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
80c0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
80d0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
80e0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
80f0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
8100: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8110: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8120: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8130: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8140: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8150: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8160: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8170: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8180: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8190: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
81a0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
81b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
81c0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
81d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81e0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
81f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8200: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8210: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8220: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8230: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8240: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8250: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8260: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8270: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8280: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8290: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
82a0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
82b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
82c0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
82d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82e0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
82f0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8300: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8310: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8320: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8330: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8340: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8350: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8360: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8370: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8380: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8390: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
83a0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
83b0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
83c0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
83d0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
83e0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
83f0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8400: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8410: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8420: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8430: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8440: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8450: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8460: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8470: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8480: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8490: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
84a0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
84b0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
84c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
84d0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
84e0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
84f0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8500: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8510: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8520: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8530: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
8540: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8560: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8570: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8580: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8590: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
85a0: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
85b0: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
85c0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
85d0: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
85e0: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
85f0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
8600: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
8610: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
8620: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
8630: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
8640: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8650: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8660: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8670: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8680: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8690: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
86a0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
86b0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
86c0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
86e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86f0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8700: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8710: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8720: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
8730: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
8740: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8750: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8760: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8770: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8780: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8790: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
87a0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
87b0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
87c0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
87d0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
87e0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
87f0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
8800: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
8810: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8820: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
8830: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8840: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8850: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8860: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8870: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8880: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8890: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
88a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
88b0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
88c0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
88d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
88e0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
88f0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8900: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8910: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8920: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8930: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8940: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8950: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8960: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8970: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8980: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8990: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
89a0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
89b0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
89c0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
89d0: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
89e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
89f0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8a00: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a10: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8a20: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8a30: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8a40: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8a50: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8a60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a70: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8a80: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8a90: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8aa0: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8ab0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8ac0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8ad0: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8ae0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8af0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8b00: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8b10: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8b20: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8b30: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8b40: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8b50: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8b60: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8b70: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8b80: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8b90: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8ba0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8bb0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8bc0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8bd0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8be0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8bf0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8c00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8c10: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8c20: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8c30: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8c40: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8c50: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8c60: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8c70: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8c80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c90: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8ca0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8cb0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8cc0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8cd0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8ce0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8cf0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8d00: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8d10: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8d20: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8d30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8d40: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8d50: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8d60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8d70: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8d80: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8d90: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8da0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8db0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8dc0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8dd0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8de0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8df0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8e00: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8e10: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8e20: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8e30: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8e40: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8e50: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8e60: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8e70: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8e80: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8e90: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8ea0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8eb0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8ec0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8ed0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8ee0: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8ef0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8f00: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8f10: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8f20: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8f30: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8f40: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8f50: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8f60: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8f70: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8f80: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8f90: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8fa0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8fb0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8fc0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8fd0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8fe0: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8ff0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9000: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
9010: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9020: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
9030: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9040: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
9050: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9060: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9070: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9080: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9090: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
90a0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
90b0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
90c0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
90d0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
90e0: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
90f0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
9100: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
9110: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
9120: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
9130: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
9140: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
9150: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9160: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9170: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9180: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9190: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
91a0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
91b0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
91c0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
91d0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
91e0: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
91f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9200: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9210: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9220: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9230: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9240: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9250: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9260: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9270: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9280: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9290: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
92a0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
92b0: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
92c0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
92d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
92e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
92f0: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
9300: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9310: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
9320: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9330: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9340: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9350: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9360: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9370: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
9380: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
9390: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
93a0: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
93b0: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
93c0: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
93d0: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
93e0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
93f0: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
9400: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
9410: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
9420: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9430: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
9440: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
9450: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9460: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
9470: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9480: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
9490: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
94a0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
94b0: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
94c0: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
94d0: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
94e0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
94f0: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
9500: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
9510: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
9520: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
9530: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
9540: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
9550: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
9560: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
9570: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
9580: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
9590: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
95a0: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
95b0: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
95c0: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
95d0: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
95e0: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
95f0: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
9600: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
9610: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
9620: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
9630: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9640: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
9650: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
9660: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
9670: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
9680: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
9690: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
96a0: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
96b0: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
96c0: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
96d0: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
96e0: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
96f0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
9700: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
9710: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9720: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
9730: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
9740: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
9750: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9760: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9770: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9780: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
9790: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
97a0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
97b0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
97c0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
97d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
97e0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
97f0: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
9800: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
9810: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
9820: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9830: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9840: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
9850: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9860: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
9870: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
9880: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
9890: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
98a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
98b0: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
98c0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
98d0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
98e0: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
98f0: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9900: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9910: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9920: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
9930: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9940: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9950: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9960: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
9970: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9980: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9990: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
99a0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
99b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
99c0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
99d0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
99e0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
99f0: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9a00: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9a10: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9a20: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9a30: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9a40: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9a50: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9a60: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
9a70: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
9a80: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
9a90: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
9aa0: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9ab0: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9ac0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9ad0: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9ae0: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9af0: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9b00: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9b10: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9b20: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9b30: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9b40: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9b50: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9b60: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
9b70: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
9b80: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
9b90: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
9ba0: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9bb0: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9bc0: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9bd0: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9be0: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9bf0: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9c00: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9c10: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9c20: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9c30: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9c40: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9c50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9c60: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9c70: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
9c80: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
9c90: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
9ca0: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9cb0: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9cc0: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
9cd0: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
9ce0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
9cf0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
9d00: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
9d10: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
9d20: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
9d30: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
9d40: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
9d50: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
9d60: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
9d70: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
9d80: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
9d90: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
9da0: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
9db0: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
9dc0: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
9dd0: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
9de0: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
9df0: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
9e00: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9e10: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9e20: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9e30: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9e40: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
9e50: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9e60: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9e70: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
9e80: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
9e90: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
9ea0: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
9eb0: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
9ec0: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
9ed0: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
9ee0: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
9ef0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
9f00: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
9f10: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
9f20: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
9f30: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
9f40: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
9f50: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
9f60: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
9f70: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
9f80: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
9f90: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
9fa0: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
9fb0: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
9fc0: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
9fd0: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
9fe0: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
9ff0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a000: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a010: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a020: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a030: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a040: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
a050: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a060: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
a070: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
a080: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
a090: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
a0a0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a0b0: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a0c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a0d0: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a0e0: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a0f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a100: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a110: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a120: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
a130: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
a140: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
a150: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
a160: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a170: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a180: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a190: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a1a0: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
a1b0: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
a1c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a1d0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a1e0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a1f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a200: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a210: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a220: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a230: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a240: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
a250: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
a260: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
a270: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
a280: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
a290: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
a2a0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
a2b0: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
a2c0: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
a2d0: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
a2e0: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
a2f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a300: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a310: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a320: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a330: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a340: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a350: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a360: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
a370: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
a380: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
a390: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
a3a0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a3b0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a3c0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a3d0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a3e0: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
a3f0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
a400: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a410: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
a420: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a430: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a440: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
a450: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
a460: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
a470: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
a480: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
a490: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
a4a0: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
a4b0: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
a4c0: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
a4d0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
a4e0: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
a4f0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
a500: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
a510: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
a520: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
a530: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
a540: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a550: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
a560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a570: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
a580: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
a590: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
a5a0: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
a5b0: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
a5c0: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
a5d0: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
a5e0: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
a5f0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
a600: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
a610: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a620: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
a630: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
a640: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
a650: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
a660: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
a670: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
a680: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
a690: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a6a0: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
a6b0: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
a6c0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
a6d0: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
a6e0: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
a6f0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
a700: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
a710: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
a720: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
a730: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
a740: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
a750: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
a760: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
a770: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a780: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
a790: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
a7a0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a7b0: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
a7c0: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
a7d0: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
a7e0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
a7f0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
a800: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a810: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
a820: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
a830: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a840: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
a850: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
a860: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
a870: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
a880: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
a890: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
a8a0: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
a8b0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
a8c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a8d0: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
a8e0: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
a8f0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
a900: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
a910: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
a920: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
a930: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
a940: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
a950: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
a960: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
a970: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
a980: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
a990: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
a9a0: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
a9b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a9c0: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
a9d0: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
a9e0: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
a9f0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
aa00: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
aa10: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aa20: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
aa30: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
aa40: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
aa50: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
aa60: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
aa70: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
aa80: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
aa90: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
aaa0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
aab0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
aac0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
aad0: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
aae0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
aaf0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
ab00: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
ab10: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
ab20: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
ab30: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ab40: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
ab50: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
ab60: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
ab70: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
ab80: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
ab90: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
aba0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
abb0: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
abc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
abd0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
abe0: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
abf0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
ac00: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
ac10: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
ac20: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
ac30: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
ac40: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
ac50: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
ac60: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
ac70: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
ac80: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
ac90: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
aca0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
acb0: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
acc0: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
acd0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
ace0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
acf0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
ad00: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
ad10: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
ad20: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
ad30: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
ad40: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
ad50: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ad60: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
ad70: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
ad80: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
ad90: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
ada0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
adb0: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
adc0: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
add0: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
ade0: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
adf0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
ae00: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
ae10: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
ae20: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
ae30: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
ae40: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
ae50: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
ae60: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
ae70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ae80: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
ae90: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
aea0: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
aeb0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
aec0: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
aed0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
aee0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
aef0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
af00: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
af10: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
af20: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
af30: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
af40: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
af50: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
af60: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
af70: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
af80: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
af90: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
afa0: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
afb0: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
afc0: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
afd0: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
afe0: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
aff0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b000: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b010: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b020: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b030: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b040: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
b050: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
b060: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
b070: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
b080: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
b090: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
b0a0: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
b0b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
b0c0: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
b0d0: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
b0e0: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
b0f0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
b100: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
b110: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
b120: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
b130: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
b140: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
b150: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
b160: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
b170: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
b180: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
b190: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
b1a0: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
b1b0: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
b1c0: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
b1d0: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
b1e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
b1f0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
b200: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
b210: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
b220: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
b230: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
b240: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
b250: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
b260: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
b270: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
b280: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
b290: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
b2a0: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
b2b0: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
b2c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b2d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b2e0: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
b2f0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
b300: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
b310: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b320: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
b330: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
b340: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
b350: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b360: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
b370: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
b380: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
b390: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
b3a0: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b3b0: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
b3c0: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
b3d0: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
b3e0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b3f0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
b400: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
b410: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
b420: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
b430: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
b440: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b450: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b460: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b470: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b480: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b490: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b4a0: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b4b0: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b4c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b4d0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b4e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b4f0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b500: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b510: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b520: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b530: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b540: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b550: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b560: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b570: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b580: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b590: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b5a0: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b5b0: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b5c0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b5d0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b5e0: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b5f0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b600: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b610: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b620: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b630: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b640: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b650: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b660: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b670: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b680: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b690: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b6a0: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b6b0: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b6c0: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b6d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b6e0: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b6f0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b700: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b710: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b720: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b730: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b740: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b750: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b760: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b770: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b780: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b790: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b7a0: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b7b0: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b7c0: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b7d0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b7e0: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b7f0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b800: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b810: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b820: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b830: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b840: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b850: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
b860: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
b870: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
b880: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
b890: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
b8a0: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
b8b0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
b8c0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
b8d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b8e0: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
b8f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b900: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
b910: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
b920: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
b930: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
b940: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
b950: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
b960: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
b970: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
b980: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
b990: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
b9a0: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
b9b0: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
b9c0: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
b9d0: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
b9e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
b9f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
ba00: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
ba10: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
ba20: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
ba30: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
ba40: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
ba50: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
ba60: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
ba70: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
ba80: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
ba90: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
baa0: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
bab0: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
bac0: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
bad0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
bae0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
baf0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
bb00: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
bb10: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
bb20: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
bb30: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bb40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
bb50: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
bb60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
bb70: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
bb80: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
bb90: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
bba0: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
bbb0: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
bbc0: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
bbd0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
bbe0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
bbf0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
bc00: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
bc10: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
bc20: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
bc30: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
bc40: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
bc50: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
bc60: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
bc70: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
bc80: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
bc90: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
bca0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
bcb0: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
bcc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
bcd0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
bce0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
bcf0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
bd00: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
bd10: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
bd20: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
bd30: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
bd40: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
bd50: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
bd60: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bd70: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
bd80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
bd90: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
bda0: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
bdb0: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
bdc0: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
bdd0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
bde0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
bdf0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
be00: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
be10: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
be20: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
be30: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
be40: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
be50: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
be60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
be70: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
be80: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
be90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
bea0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
beb0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
bec0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
bed0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
bee0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
bef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
bf00: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
bf10: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
bf20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
bf30: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
bf40: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
bf50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
bf60: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
bf70: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
bf80: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
bf90: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
bfa0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
bfb0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
bfc0: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
bfd0: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
bfe0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
bff0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
c000: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c010: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
c020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
c030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c040: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
c050: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
c060: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c070: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
c080: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
c090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c0a0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
c0b0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
c0c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c0d0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
c0e0: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
c0f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c100: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
c110: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
c120: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c130: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
c140: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
c150: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c160: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
c170: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
c180: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
c190: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
c1a0: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
c1b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c1c0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
c1d0: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
c1e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c1f0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
c200: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
c210: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c220: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
c230: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
c240: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c250: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
c260: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
c270: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c290: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
c2a0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
c2b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c2c0: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
c2d0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
c2e0: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
c2f0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c300: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
c310: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
c320: 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20  ../* deprecated 
c330: 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  names */.#define
c340: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
c350: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
c360: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
c370: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
c380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
c390: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c3a0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
c3b0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
c3c0: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
c3d0: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
c3e0: 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f           SQLITE_
c3f0: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
c400: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
c410: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
c420: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
c430: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
c440: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
c450: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
c460: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
c470: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
c480: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
c490: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
c4a0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
c4b0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
c4c0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
c4d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
c4e0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
c4f0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
c500: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
c510: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
c520: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
c530: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
c540: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
c550: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
c560: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
c570: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
c580: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
c590: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
c5a0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
c5b0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
c5c0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
c5d0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
c5e0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
c5f0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
c600: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
c610: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
c620: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
c630: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
c640: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
c650: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
c660: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
c670: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
c680: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
c690: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
c6a0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
c6b0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
c6c0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
c6d0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
c6e0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
c6f0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
c700: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
c710: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
c720: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
c730: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
c740: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
c750: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
c760: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
c770: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
c780: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
c790: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
c7a0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
c7b0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
c7c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
c7d0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
c7e0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
c7f0: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
c800: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
c810: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
c820: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
c830: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
c840: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
c850: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
c860: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
c870: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
c880: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
c890: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
c8a0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
c8b0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
c8c0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
c8d0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
c8e0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
c8f0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
c900: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
c910: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
c920: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
c930: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
c940: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
c950: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
c960: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
c970: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
c980: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
c990: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
c9a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c9b0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
c9c0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
c9d0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
c9e0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
c9f0: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
ca00: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
ca10: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
ca20: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
ca30: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
ca40: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
ca50: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
ca60: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
ca70: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
ca80: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
ca90: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
caa0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
cab0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
cac0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
cad0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
cae0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
caf0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
cb00: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
cb10: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
cb20: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
cb30: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
cb40: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
cb50: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
cb60: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
cb70: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
cb80: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
cb90: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
cba0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
cbb0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
cbc0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
cbd0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
cbe0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
cbf0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
cc00: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
cc10: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
cc20: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
cc30: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
cc40: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
cc50: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
cc60: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
cc70: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
cc80: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
cc90: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
cca0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
ccb0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
ccc0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
ccd0: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
cce0: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
ccf0: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
cd00: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
cd10: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
cd20: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
cd30: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
cd40: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
cd50: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
cd60: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
cd70: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
cd80: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
cd90: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
cda0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
cdb0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
cdc0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
cdd0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
cde0: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
cdf0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
ce00: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
ce10: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
ce20: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
ce30: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
ce40: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
ce50: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
ce60: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
ce70: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
ce80: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
ce90: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
cea0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
ceb0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
cec0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
ced0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
cee0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
cef0: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
cf00: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
cf10: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
cf20: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
cf30: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
cf40: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
cf50: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
cf60: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
cf70: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
cf80: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
cf90: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
cfa0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
cfb0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
cfc0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
cfd0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
cfe0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
cff0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
d000: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
d010: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
d020: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
d030: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
d040: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
d050: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
d060: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
d070: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
d080: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
d090: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
d0a0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
d0b0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
d0c0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
d0d0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
d0e0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d0f0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d100: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
d110: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
d120: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
d130: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
d140: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
d150: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
d160: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d170: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
d180: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d190: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
d1a0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
d1b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
d1c0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d1d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d1e0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
d1f0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d200: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
d210: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d220: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
d230: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d240: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
d250: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
d260: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
d270: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
d280: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
d290: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
d2a0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
d2b0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
d2c0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
d2d0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
d2e0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
d2f0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
d300: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
d310: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
d320: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
d330: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
d340: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
d350: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
d360: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
d370: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
d380: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
d390: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
d3a0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
d3b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
d3c0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
d3d0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
d3e0: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
d3f0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
d400: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
d410: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
d420: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
d430: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
d440: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
d450: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
d460: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
d470: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
d480: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
d490: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
d4a0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
d4b0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
d4c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
d4d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
d4e0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
d4f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d500: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
d510: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
d520: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d530: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
d540: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
d550: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
d560: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
d570: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
d580: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d590: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
d5a0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
d5b0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
d5c0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
d5d0: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
d5e0: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
d5f0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
d600: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
d610: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
d620: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
d630: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
d640: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
d650: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
d660: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
d670: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
d680: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
d690: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
d6a0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
d6b0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
d6c0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
d6d0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
d6e0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
d6f0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
d700: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
d710: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
d720: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
d730: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
d740: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
d750: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
d760: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
d770: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
d780: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
d790: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
d7a0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
d7b0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
d7c0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
d7d0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
d7e0: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
d7f0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
d800: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
d810: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
d820: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
d830: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
d840: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
d850: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
d860: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
d870: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
d880: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
d890: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
d8a0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
d8b0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
d8c0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
d8d0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d8e0: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
d8f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d900: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
d910: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
d920: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
d930: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
d940: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
d950: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
d960: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
d970: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
d980: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
d990: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
d9a0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
d9b0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
d9c0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
d9d0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
d9e0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
d9f0: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
da00: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
da10: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
da20: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
da30: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
da40: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
da50: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
da60: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
da70: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
da80: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
da90: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
daa0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
dab0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
dac0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
dad0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
dae0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
daf0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
db00: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
db10: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
db20: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
db30: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
db40: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
db50: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
db60: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
db70: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
db80: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
db90: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
dba0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
dbb0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
dbc0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
dbd0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
dbe0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
dbf0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
dc00: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
dc10: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
dc20: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
dc30: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
dc40: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
dc50: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
dc60: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
dc70: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
dc80: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
dc90: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
dca0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
dcb0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
dcc0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
dcd0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
dce0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
dcf0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
dd00: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
dd10: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
dd20: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
dd30: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
dd40: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
dd50: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
dd60: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
dd70: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
dd80: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
dd90: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
dda0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
ddb0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
ddc0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
ddd0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
dde0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
ddf0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
de00: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
de10: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
de20: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
de30: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
de40: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
de50: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
de60: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
de70: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
de80: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
de90: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
dea0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
deb0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
dec0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
ded0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
dee0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
def0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
df00: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
df10: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
df20: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
df30: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
df40: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
df50: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
df60: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
df70: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
df80: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
df90: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
dfa0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
dfb0: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
dfc0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
dfd0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
dfe0: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
dff0: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
e000: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
e010: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e020: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
e030: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
e040: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
e050: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
e060: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
e070: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
e080: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
e090: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
e0a0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
e0b0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
e0c0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
e0d0: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
e0e0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
e0f0: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
e100: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
e110: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
e120: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
e130: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
e140: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
e150: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
e160: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
e170: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
e180: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
e190: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
e1a0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
e1b0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
e1c0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
e1d0: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
e1e0: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
e1f0: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
e200: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
e210: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
e220: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
e230: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
e240: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
e250: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
e260: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
e270: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
e280: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
e290: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
e2a0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
e2b0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
e2c0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
e2d0: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
e2e0: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
e2f0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
e300: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
e310: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
e320: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
e330: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
e340: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
e350: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
e360: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
e370: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
e380: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
e390: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
e3a0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
e3b0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
e3c0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
e3d0: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
e3e0: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
e3f0: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
e400: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
e410: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
e420: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
e430: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
e440: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
e450: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
e460: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
e470: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
e480: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
e490: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
e4a0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
e4b0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
e4c0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
e4d0: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
e4e0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
e4f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
e500: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
e510: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
e520: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
e530: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
e540: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
e550: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
e560: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
e570: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
e580: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
e590: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
e5a0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
e5b0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
e5c0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
e5d0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
e5e0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
e5f0: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
e600: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
e610: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
e620: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
e630: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e640: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
e650: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
e660: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
e670: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
e680: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
e690: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
e6a0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e6b0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
e6c0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
e6d0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
e6e0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e6f0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
e700: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
e710: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
e720: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
e730: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e740: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
e750: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
e760: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
e770: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
e780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
e790: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
e7a0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
e7b0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
e7c0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
e7d0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
e7e0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
e7f0: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
e800: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
e810: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
e820: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
e830: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
e840: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
e850: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
e860: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
e870: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
e880: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
e890: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
e8a0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
e8b0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e8c0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
e8d0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
e8e0: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
e8f0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
e900: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
e910: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e920: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e930: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
e940: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e950: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
e960: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
e970: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
e980: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
e990: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
e9a0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e9b0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
e9c0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
e9d0: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
e9e0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
e9f0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
ea00: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
ea10: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
ea20: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
ea30: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
ea40: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
ea50: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
ea60: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
ea70: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
ea80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ea90: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
eaa0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
eab0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
eac0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
ead0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
eae0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
eaf0: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
eb00: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
eb10: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
eb20: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
eb30: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
eb40: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
eb50: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
eb60: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
eb70: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
eb80: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
eb90: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
eba0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
ebb0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
ebc0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
ebd0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
ebe0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
ebf0: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
ec00: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
ec10: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
ec20: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
ec30: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
ec40: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
ec50: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
ec60: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
ec70: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
ec80: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ec90: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
eca0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
ecb0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
ecc0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
ecd0: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
ece0: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
ecf0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
ed00: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
ed10: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
ed20: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
ed30: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
ed40: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
ed50: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
ed60: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ed70: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
ed80: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
ed90: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
eda0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
edb0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
edc0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
edd0: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
ede0: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
edf0: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
ee00: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
ee10: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
ee20: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
ee30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ee40: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
ee50: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
ee60: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
ee70: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
ee80: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
ee90: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
eea0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
eeb0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
eec0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
eed0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
eee0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
eef0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
ef00: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
ef10: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
ef20: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
ef30: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
ef40: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
ef50: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
ef60: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
ef70: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
ef80: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
ef90: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
efa0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
efb0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
efc0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
efd0: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
efe0: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
eff0: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
f000: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
f010: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f020: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
f030: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
f040: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
f050: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
f060: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
f070: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
f080: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
f090: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
f0a0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
f0b0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
f0c0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f0d0: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
f0e0: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
f0f0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
f100: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
f110: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
f120: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
f130: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f140: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
f150: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f160: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
f170: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
f180: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
f190: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f1a0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
f1b0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
f1c0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
f1d0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
f1e0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
f1f0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f200: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
f210: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
f220: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
f230: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
f240: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
f250: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
f260: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20  ** was given on 
f270: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
f280: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
f290: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
f2a0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
f2b0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
f2c0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
f2d0: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
f2e0: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
f2f0: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
f300: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
f310: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
f320: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
f330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f340: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
f350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f360: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
f370: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
f380: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
f390: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
f3a0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
f3b0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
f3c0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
f3d0: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
f3e0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
f3f0: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
f400: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
f410: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
f420: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
f430: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
f440: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
f450: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
f460: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
f470: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
f480: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
f490: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
f4a0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
f4b0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
f4c0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
f4d0: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
f4e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
f4f0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
f500: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
f510: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f520: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f530: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
f540: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
f550: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
f560: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f570: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
f580: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
f590: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
f5a0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
f5b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f5c0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
f5d0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
f5e0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
f5f0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
f600: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
f610: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
f620: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
f630: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
f640: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
f650: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
f660: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
f670: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
f680: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
f690: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
f6a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f6b0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
f6c0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
f6d0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
f6e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f6f0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
f700: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
f710: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
f720: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
f730: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
f740: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
f750: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
f760: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
f770: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
f780: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f790: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
f7a0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
f7b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f7c0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
f7d0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
f7e0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
f7f0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
f800: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
f810: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f820: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
f830: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
f840: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
f850: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
f860: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f870: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
f880: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
f890: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
f8a0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
f8b0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f8c0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
f8d0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
f8e0: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
f8f0: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
f900: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f910: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
f920: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
f930: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
f940: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
f950: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
f960: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
f970: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
f980: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
f990: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
f9a0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
f9b0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
f9c0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
f9d0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
f9e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f9f0: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
fa00: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
fa10: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
fa20: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
fa30: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
fa40: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
fa50: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fa60: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
fa70: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
fa80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fa90: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
faa0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
fab0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
fac0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
fad0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
fae0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
faf0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
fb00: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fb10: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
fb20: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
fb30: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
fb40: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
fb50: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
fb60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
fb70: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
fb80: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
fb90: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
fba0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
fbb0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
fbc0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
fbd0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
fbe0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
fbf0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
fc00: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
fc10: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
fc20: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
fc30: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
fc40: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
fc50: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
fc60: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
fc70: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
fc80: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
fc90: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
fca0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
fcb0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
fcc0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
fcd0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
fce0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
fcf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fd00: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
fd10: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
fd20: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
fd30: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
fd40: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
fd50: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
fd60: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
fd70: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
fd80: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
fd90: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
fda0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
fdb0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
fdc0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
fdd0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
fde0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
fdf0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
fe00: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fe10: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
fe20: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
fe30: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
fe40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fe50: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
fe60: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
fe70: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
fe80: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
fe90: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
fea0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
feb0: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
fec0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
fed0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
fee0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
fef0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
ff00: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
ff10: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
ff20: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
ff30: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
ff40: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
ff50: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
ff60: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
ff70: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
ff80: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
ff90: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
ffa0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
ffb0: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
ffc0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
ffd0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
ffe0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
fff0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
10000 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
10010 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
10020 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
10030 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
10040 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
10050 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
10060 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
10070 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10080 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
10090 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
100a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
100b0 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
100c0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
100d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
100e0 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
100f0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
10100 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
10110 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
10120 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
10130 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
10140 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
10150 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
10160 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
10170 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
10180 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
10190 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
101a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
101b0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
101c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
101d0 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
101e0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
101f0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
10200 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
10210 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
10220 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
10230 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
10240 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
10250 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
10260 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
10270 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
10280 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
10290 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
102a0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
102b0 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
102c0 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
102d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
102e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
102f0 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
10300 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
10310 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
10320 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
10330 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
10340 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
10350 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
10360 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
10370 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
10380 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
10390 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
103a0 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
103b0 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
103c0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
103d0 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
103e0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
103f0 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
10400 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
10410 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
10420 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
10430 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
10440 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
10450 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
10460 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
10470 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
10480 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
10490 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
104a0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
104b0 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
104c0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
104d0 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
104e0 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
104f0 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
10500 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10510 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
10520 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
10530 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
10540 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
10550 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
10560 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
10570 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
10580 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
10590 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
105a0 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
105b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
105c0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
105d0 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
105e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
105f0 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
10600 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
10610 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
10620 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
10630 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
10640 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
10650 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
10660 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
10670 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
10680 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
10690 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
106a0 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
106b0 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
106c0 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
106d0 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
106e0 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
106f0 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
10700 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65  ** <b>The sqlite
10710 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10720 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
10730 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c  adsafe. The appl
10740 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
10750 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  ensure that no o
10760 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
10770 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
10780 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
10790 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
107a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
107b0 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a   running.</b>.**
107c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
107d0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
107e0 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ce.** may only b
107f0 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
10800 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
10810 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
10820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
10830 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
10840 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
10850 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10860 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
10870 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10880 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
10890 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
108a0 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
108b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
108c0 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
108d0 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
108e0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
108f0 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
10900 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
10910 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
10920 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
10930 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10940 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
10950 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
10960 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
10970 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
10980 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
10990 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
109a0 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
109b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
109c0 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
109d0 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
109e0 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
109f0 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
10a00 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
10a10 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
10a20 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10a30 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
10a40 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
10a50 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10a60 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
10a70 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
10a80 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
10a90 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10aa0 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
10ab0 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
10ac0 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
10ad0 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
10ae0 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
10af0 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
10b00 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
10b10 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
10b20 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
10b30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10b40 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
10b50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10b60 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
10b70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
10b80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
10b90 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te3.**.** The sq
10ba0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10bb0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
10bc0 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
10bd0 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10be0 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
10bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
10c00 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
10c10 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
10c20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10c30 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
10c40 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
10c50 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
10c60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10c70 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
10c80 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
10c90 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
10ca0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
10cb0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
10cc0 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
10cd0 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
10ce0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
10cf0 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
10d00 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
10d10 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
10d20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
10d30 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
10d40 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
10d50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
10d60 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
10d70 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
10d80 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
10d90 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
10da0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10db0 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
10dc0 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
10dd0 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
10de0 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
10df0 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
10e00 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
10e10 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
10e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
10e30 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
10e40 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
10e50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
10e60 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
10e70 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
10e80 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
10e90 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
10ea0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
10eb0 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
10ec0 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
10ed0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10ee0 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
10ef0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
10f00 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
10f10 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
10f20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10f30 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
10f40 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
10f50 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
10f60 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
10f70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10f80 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
10f90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10fa0 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
10fb0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
10fc0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
10fd0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
10fe0 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
10ff0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
11000 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
11010 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
11020 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
11030 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
11040 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
11050 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
11060 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
11070 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
11080 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
11090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
110a0 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
110b0 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
110c0 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
110d0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
110e0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
110f0 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
11100 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
11110 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
11120 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
11130 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
11140 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
11150 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
11160 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
11170 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
11180 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
11190 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
111a0 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
111b0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
111c0 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
111d0 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
111e0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
111f0 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
11200 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
11210 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
11220 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
11230 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
11240 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
11250 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
11260 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
11270 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
11280 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
11290 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
112a0 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
112b0 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
112c0 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
112d0 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
112e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
112f0 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
11300 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
11310 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
11320 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
11330 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
11340 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
11350 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
11360 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
11370 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
11380 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
11390 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
113a0 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
113b0 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
113c0 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
113d0 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
113e0 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
113f0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
11400 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
11410 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
11420 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
11430 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
11440 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
11450 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
11460 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
11470 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
11480 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
11490 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
114a0 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
114b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
114c0 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
114d0 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
114e0 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
114f0 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
11500 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
11510 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
11520 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
11530 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
11540 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
11550 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
11560 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
11570 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
11580 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
11590 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
115a0 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
115b0 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
115c0 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
115d0 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
115e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
115f0 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
11600 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
11610 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
11620 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
11630 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
11640 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
11650 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
11660 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
11670 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
11680 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
11690 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
116a0 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
116b0 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
116c0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
116d0 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
116e0 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
116f0 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
11700 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
11710 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
11720 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
11730 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
11740 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
11750 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
11760 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
11770 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11780 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
11790 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
117a0 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
117b0 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
117c0 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
117d0 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
117e0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
117f0 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
11800 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
11810 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
11820 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
11830 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
11840 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
11850 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
11860 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
11870 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
11880 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
11890 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
118a0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
118b0 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
118c0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
118d0 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
118e0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
118f0 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
11900 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
11910 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
11920 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
11930 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
11940 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
11950 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
11960 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11970 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11980 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
11990 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
119a0 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
119b0 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
119c0 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
119d0 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
119e0 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
119f0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
11a00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11a10 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
11a20 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
11a30 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
11a40 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
11a50 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
11a60 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
11a70 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
11a80 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
11a90 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
11aa0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
11ab0 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
11ac0 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
11ad0 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
11ae0 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
11af0 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
11b00 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11b10 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
11b20 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
11b30 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11b40 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
11b50 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
11b60 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
11b70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11b80 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
11b90 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
11ba0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
11bb0 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
11bc0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
11bd0 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
11be0 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
11bf0 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
11c00 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
11c10 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
11c20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
11c30 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
11c40 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
11c50 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
11c60 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11c70 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
11c80 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
11c90 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
11ca0 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
11cb0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11cc0 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
11cd0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11ce0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
11cf0 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
11d00 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
11d10 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
11d20 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11d30 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
11d40 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
11d50 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
11d60 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
11d70 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
11d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11d90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
11da0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
11db0 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
11dc0 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
11dd0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
11de0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
11df0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
11e00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
11e10 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
11e20 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
11e30 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
11e40 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11e50 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
11e60 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
11e70 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11e80 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
11e90 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
11ea0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
11eb0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
11ec0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
11ed0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
11ee0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
11ef0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
11f00 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
11f10 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
11f20 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
11f30 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
11f40 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
11f50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
11f60 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
11f70 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
11f80 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
11f90 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
11fa0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
11fb0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
11fc0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
11fd0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
11fe0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
11ff0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12000 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
12010 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
12020 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
12030 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
12040 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
12050 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
12060 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
12070 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
12080 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
12090 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
120a0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
120b0 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
120c0 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
120d0 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
120e0 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
120f0 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
12100 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
12110 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
12120 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12130 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12140 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12150 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12160 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
12170 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
12180 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
12190 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
121a0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
121b0 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
121c0 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
121d0 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
121e0 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
121f0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
12200 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
12210 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12220 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
12230 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12240 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
12250 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12260 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12270 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
12280 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
12290 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
122a0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
122b0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
122c0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
122d0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
122e0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
122f0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12300 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
12310 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
12320 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
12330 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
12340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12350 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
12360 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
12370 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
12380 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
12390 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
123a0 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
123b0 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
123c0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
123d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
123e0 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
123f0 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
12400 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
12410 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
12420 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
12430 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
12440 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
12450 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
12460 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
12470 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
12480 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12490 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
124a0 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
124b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
124c0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
124d0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
124e0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
124f0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12500 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12510 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
12520 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
12530 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
12540 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12550 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
12560 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12570 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12580 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
12590 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
125a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
125b0 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
125c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
125d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
125e0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
125f0 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
12600 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12610 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12620 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12630 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12640 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12650 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12660 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12670 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
12680 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
12690 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
126a0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
126b0 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
126c0 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
126d0 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
126e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
126f0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12700 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
12710 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
12720 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
12730 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
12740 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12750 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
12760 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
12770 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
12780 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
12790 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
127a0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
127b0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
127c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
127d0 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
127e0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
127f0 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
12800 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
12810 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
12820 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
12830 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12840 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
12850 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
12860 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
12870 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12880 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
12890 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
128a0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
128b0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
128c0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
128d0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
128e0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
128f0 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
12900 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
12910 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
12920 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
12930 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12940 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12950 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12960 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12970 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
12980 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
12990 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
129a0 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
129b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
129c0 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
129d0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
129e0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74  ONFIG_MALLOC opt
129f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12a00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12a10 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
12a20 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12a30 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12a40 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12a50 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
12a60 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
12a70 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
12a80 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
12a90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12aa0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12ab0 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
12ac0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
12ad0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12ae0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
12af0 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
12b00 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
12b10 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
12b20 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
12b30 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12b40 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12b50 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
12b60 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12b70 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
12b80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12b90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12ba0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
12bb0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12bc0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12bd0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12be0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f  NFIG_GETMALLOC o
12bf0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12c00 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12c10 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
12c20 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12c30 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12c40 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12c50 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
12c60 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12c70 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
12c80 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
12c90 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
12ca0 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
12cb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12cc0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
12cd0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
12ce0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
12cf0 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
12d00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
12d10 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
12d20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
12d30 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
12d40 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
12d50 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
12d60 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
12d70 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
12d80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12d90 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12da0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12db0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
12dc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
12dd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12de0 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20  EMSTATUS option 
12df0 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
12e00 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
12e10 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65  t,.** interprete
12e20 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
12e30 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
12e40 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
12e50 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d  llection of.** m
12e60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12e70 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
12e80 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
12e90 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12ea0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
12eb0 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
12ec0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
12ed0 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
12ee0 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
12ef0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
12f00 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
12f10 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
12f20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12f30 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
12f40 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12f50 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
12f60 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
12f70 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34  sqlite3_status64
12f80 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
12f90 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
12fa0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12fb0 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
12fc0 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
12fd0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
12fe0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
12ff0 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
13000 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
13010 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
13020 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
13030 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
13040 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
13050 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
13060 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13070 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
13080 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13090 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
130a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
130b0 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e  G_SCRATCH option
130c0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
130d0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
130e0 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
130f0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72   can use for scr
13100 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28  atch memory.  ^(
13110 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
13120 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
13130 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13140 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65  RATCH:  A pointe
13150 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
13160 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
13170 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
13180 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
13190 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
131a0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
131b0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
131c0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
131d0 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
131e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
131f0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13200 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54  ions (N).)^.** T
13210 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13220 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
13230 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
13240 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
13250 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
13260 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
13270 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
13280 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72  will not use mor
13290 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
132a0 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
132b0 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  hread..** ^SQLit
132c0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
132d0 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62  uest a scratch b
132e0 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
132f0 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
13300 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
13310 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  page size..** ^I
13320 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
13330 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
13340 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
13350 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
13360 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
13370 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13380 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
13390 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
133a0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
133b0 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
133c0 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e  emory needed.<p>
133d0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70  .** ^When the ap
133e0 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64  plication provid
133f0 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66  es any amount of
13400 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
13410 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
13420 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20  CONFIG_SCRATCH, 
13430 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e  SQLite avoids un
13440 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a  necessary large.
13450 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
13460 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69  oc|heap allocati
13470 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61  ons]..** This ca
13480 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70  n help [Robson p
13490 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d  roof|prevent mem
134a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
134b0 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20  ailures] due to 
134c0 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74  heap.** fragment
134d0 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d  ation in low-mem
134e0 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73  ory embedded sys
134f0 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tems..** </dd>.*
13500 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13510 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
13520 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13530 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
13540 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
13550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13560 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70  ECACHE option sp
13570 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79  ecifies a memory
13580 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51   pool.** that SQ
13590 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
135a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
135b0 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
135c0 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a  e default page.*
135d0 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
135e0 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
135f0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13600 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f  option is a no-o
13610 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  p if an applicat
13620 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
13630 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
13640 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
13650 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  d using the [SQL
13660 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13670 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  E2]..** ^There a
13680 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
13690 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
136a0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41  FIG_PAGECACHE: A
136b0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38   pointer to.** 8
136c0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65  -byte aligned me
136d0 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65  mory (pMem), the
136e0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
136f0 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73  ge cache line (s
13700 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e  z),.** and the n
13710 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c  umber of cache l
13720 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ines (N)..** The
13730 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
13740 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
13750 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
13760 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
13770 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
13780 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
13790 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
137a0 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
137b0 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
137c0 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
137d0 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
137e0 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
137f0 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
13800 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
13810 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43   using [SQLITE_C
13820 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
13830 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68  SZ]..** ^It is h
13840 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
13850 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
13860 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68  emory,.** for th
13870 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74  e sz parameter t
13880 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  o be larger than
13890 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65   necessary.  The
138a0 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e   pMem.** argumen
138b0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
138c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
138d0 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
138e0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
138f0 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  gned block of me
13900 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
13910 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68   sz*N bytes, oth
13920 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71  erwise.** subseq
13930 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
13940 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
13950 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74  When pMem is not
13960 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
13970 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65  ll strive to use
13980 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
13990 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73  ided.** to satis
139a0 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65  fy page cache ne
139b0 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63  eds, falling bac
139c0 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  k to [sqlite3_ma
139d0 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20  lloc()] if.** a 
139e0 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
139f0 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73  is larger than s
13a00 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c  z bytes or if al
13a10 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75  l of the pMem bu
13a20 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75  ffer.** is exhau
13a30 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65  sted..** ^If pMe
13a40 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  m is NULL and N 
13a50 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
13a60 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  n each database 
13a70 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f  connection.** do
13a80 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75  es an initial bu
13a90 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  lk allocation fo
13aa0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
13ab0 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ory.** from [sql
13ac0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
13ad0 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20  ufficient for N 
13ae0 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e  cache lines if N
13af0 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a   is positive or.
13b00 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79  ** of -1024*N by
13b10 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61  tes if N is nega
13b20 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69  tive, . ^If addi
13b30 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
13b40 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
13b50 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
13b60 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
13b70 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20   the initial.** 
13b80 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
13b90 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13ba0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13bb0 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f  )] separately fo
13bc0 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69  r each.** additi
13bd0 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e  onal cache line.
13be0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13c00 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
13c10 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
13c20 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13c30 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
13c40 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13c50 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13c60 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
13c70 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
13c80 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
13c90 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
13ca0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
13cb0 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
13cc0 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
13cd0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13ce0 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
13cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13d00 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
13d10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13d20 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
13d30 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
13d40 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13d50 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
13d60 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
13d70 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
13d80 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
13d90 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
13da0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
13db0 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
13dc0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
13dd0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13de0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13df0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
13e00 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
13e10 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
13e20 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
13e30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
13e40 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
13e50 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
13e60 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
13e70 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
13e80 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
13e90 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
13ea0 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
13eb0 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
13ec0 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
13ed0 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
13ee0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
13ef0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
13f00 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
13f10 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
13f20 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
13f30 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
13f40 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
13f50 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
13f60 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
13f70 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
13f80 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
13f90 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
13fa0 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
13fb0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
13fc0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
13fd0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
13fe0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13ff0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
14000 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
14010 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
14020 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
14030 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
14040 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
14050 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
14060 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
14070 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
14080 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
14090 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
140a0 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
140b0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
140c0 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
140d0 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
140e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
140f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14100 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
14110 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
14120 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14130 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14140 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
14150 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14160 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
14170 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
14180 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14190 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
141a0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
141b0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
141c0 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
141d0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
141e0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
141f0 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
14200 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
14210 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
14220 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
14230 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
14240 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
14250 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
14260 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14270 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
14280 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
14290 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
142a0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
142b0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
142c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
142d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
142e0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
142f0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14300 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14310 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
14320 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
14330 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
14340 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
14350 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
14360 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
14370 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
14380 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
14390 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
143a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
143b0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
143c0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
143d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
143e0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
143f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14400 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
14410 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14420 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14430 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
14440 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14450 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14460 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14470 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14480 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14490 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
144a0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
144b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
144c0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
144d0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
144e0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
144f0 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
14500 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14510 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14520 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14530 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
14540 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
14550 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
14560 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
14570 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
14580 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
14590 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
145a0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
145b0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
145c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
145d0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
145e0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
145f0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14600 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14610 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14620 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14630 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14640 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14650 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
14660 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
14670 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14680 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
14690 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
146a0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
146b0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
146c0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
146d0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
146e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
146f0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
14700 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14710 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
14720 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14740 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
14750 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
14760 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
14770 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
14780 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
14790 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
147a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
147b0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
147c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
147d0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
147e0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
147f0 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
14800 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
14810 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
14820 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
14830 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
14840 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
14850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14860 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
14870 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
14880 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
14890 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
148a0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
148b0 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
148c0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
148d0 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
148e0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
148f0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
14900 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
14910 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
14920 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
14930 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14940 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
14950 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14960 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
14970 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14980 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14990 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
149a0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
149b0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
149c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
149d0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
149e0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
149f0 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
14a00 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
14a10 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
14a20 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
14a30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
14a40 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
14a50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
14a60 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14a70 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14a80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14aa0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
14ab0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14ac0 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
14ad0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14ae0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14af0 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
14b00 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14b10 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
14b20 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14b30 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14b40 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14b50 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
14b60 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
14b70 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
14b80 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
14b90 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
14ba0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14bb0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
14bc0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14bd0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
14be0 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
14bf0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14c00 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
14c10 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
14c20 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
14c30 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
14c40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14c50 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
14c60 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
14c70 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
14c80 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
14c90 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
14ca0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
14cb0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
14cc0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
14cd0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
14ce0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
14cf0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
14d00 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
14d10 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
14d20 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
14d30 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
14d40 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
14d50 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
14d60 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
14d70 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14d80 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
14d90 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
14da0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
14db0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
14dc0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
14dd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14de0 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
14df0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
14e00 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14e10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14e20 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14e30 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
14e40 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
14e50 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
14e60 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14e70 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
14e80 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
14e90 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
14ea0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14eb0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
14ec0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
14ed0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
14ee0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
14ef0 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
14f00 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
14f10 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
14f20 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
14f30 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
14f40 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
14f50 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
14f60 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
14f70 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
14f80 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
14f90 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
14fa0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
14fb0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
14fc0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14fd0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
14fe0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14ff0 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
15000 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
15010 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
15020 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
15030 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
15040 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
15050 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
15060 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
15070 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
15080 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15090 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
150a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
150b0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
150c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
150d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
150e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
150f0 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
15100 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
15110 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
15120 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
15130 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
15140 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
15150 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
15160 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
15170 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
15180 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
15190 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
151a0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
151b0 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
151c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
151d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
151e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
151f0 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
15200 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
15210 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
15220 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
15230 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
15240 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
15250 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
15260 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
15270 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
15280 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
15290 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
152a0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
152b0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
152c0 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
152d0 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
152e0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
152f0 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
15300 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
15310 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
15320 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
15330 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
15340 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
15350 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
15360 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
15370 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
15380 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
15390 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
153a0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
153b0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
153c0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
153d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
153e0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
153f0 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
15400 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15410 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
15420 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
15430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15440 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15450 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
15460 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
15470 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
15480 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
15490 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
154a0 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
154b0 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
154c0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
154d0 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
154e0 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
154f0 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
15500 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
15510 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15520 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
15530 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
15540 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
15550 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
15560 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
15570 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
15580 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
15590 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
155a0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
155b0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
155c0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
155d0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
155e0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
155f0 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
15600 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
15610 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
15620 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
15630 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
15640 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
15650 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
15660 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
15670 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
15680 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
15690 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
156a0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
156b0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
156c0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
156d0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
156e0 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
156f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
15700 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15710 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
15720 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15730 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
15740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15750 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
15760 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15770 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
15780 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
15790 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
157a0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
157b0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
157c0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
157d0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
157e0 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
157f0 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
15800 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15810 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15820 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
15830 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15840 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
15850 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
15860 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
15870 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15880 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15890 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
158a0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
158b0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
158c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
158d0 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
158e0 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
158f0 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
15900 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
15910 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
15920 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
15930 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
15940 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
15950 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
15960 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
15970 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
15980 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
15990 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
159a0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
159b0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
159c0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
159d0 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
159e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
159f0 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
15a00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15a10 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
15a20 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15a30 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
15a40 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
15a50 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
15a60 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
15a70 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
15a80 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
15a90 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
15aa0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
15ab0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
15ac0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
15ad0 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
15ae0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
15af0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
15b00 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
15b10 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
15b20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15b30 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
15b40 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
15b50 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
15b60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15b70 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
15b80 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
15b90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
15ba0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
15bb0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
15bc0 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
15bd0 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
15be0 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
15bf0 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
15c00 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
15c10 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
15c20 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
15c30 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
15c40 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15c50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15c60 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
15c70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15c80 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
15c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15ca0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
15cb0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
15cc0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
15cd0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
15ce0 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
15cf0 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
15d00 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
15d10 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
15d20 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
15d30 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
15d40 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
15d50 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
15d60 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15d70 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
15d80 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
15d90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
15da0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
15db0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
15dc0 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
15dd0 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
15de0 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
15df0 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
15e00 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
15e10 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15e20 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
15e30 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
15e40 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
15e50 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
15e60 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
15e70 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
15e80 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
15e90 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
15ea0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
15eb0 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
15ec0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
15ed0 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
15ee0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
15ef0 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
15f00 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
15f10 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
15f20 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
15f30 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
15f40 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15f50 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15f60 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
15f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15f80 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
15f90 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
15fa0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15fb0 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
15fc0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15fd0 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
15fe0 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
15ff0 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
16000 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
16010 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
16020 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
16030 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
16040 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16050 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
16060 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
16070 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
16080 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
16090 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
160a0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
160b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
160c0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
160d0 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
160e0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
160f0 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
16100 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16110 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
16120 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
16130 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
16140 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
16150 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
16160 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
16170 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
16180 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
16190 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
161a0 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
161b0 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
161c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
161d0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
161e0 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
161f0 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
16200 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
16210 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
16220 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
16230 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
16240 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
16250 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16260 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
16270 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16280 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
16290 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
162a0 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
162b0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
162c0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
162d0 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
162e0 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
162f0 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
16300 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
16310 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
16320 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
16330 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
16340 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
16350 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
16360 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
16370 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
16380 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16390 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
163a0 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
163b0 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
163c0 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
163d0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
163e0 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
163f0 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
16400 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
16410 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
16420 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
16430 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
16440 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
16450 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
16460 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
16470 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
16480 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
16490 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
164a0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
164b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
164c0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
164d0 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
164e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
164f0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
16500 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
16510 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16520 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
16530 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
16540 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16550 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
16560 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
16570 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16580 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16590 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
165a0 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
165b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
165c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
165d0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
165e0 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
165f0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16600 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16620 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
16630 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16640 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
16660 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
16670 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
16680 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
16690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
166a0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
166b0 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
166c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
166d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
166e0 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
166f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16700 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16710 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16720 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
16730 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16740 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
16750 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
16760 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
16770 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
16780 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
16790 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
167a0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
167b0 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
167c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
167d0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
167e0 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
167f0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
16800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16810 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
16820 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16830 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16840 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
16850 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
16860 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16870 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
16880 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
16890 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
168a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
168b0 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
168c0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
168d0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
168e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
168f0 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
16900 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
16910 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
16920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16930 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
16940 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
16950 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
16960 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16970 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
16980 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
16990 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
169a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
169b0 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
169c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
169d0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
169e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
169f0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
16a00 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
16a10 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
16a20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16a30 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
16a40 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
16a50 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
16a60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16a70 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
16a80 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
16a90 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
16aa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16ab0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
16ac0 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
16ad0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
16ae0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
16af0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
16b00 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
16b10 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16b20 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
16b30 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16b40 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16b50 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
16b60 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
16b70 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
16b80 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16b90 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
16ba0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
16bb0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
16bc0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
16bd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16be0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
16bf0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
16c00 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
16c10 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
16c20 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
16c30 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16c40 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
16c50 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
16c60 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
16c70 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16c80 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
16c90 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
16ca0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
16cb0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
16cc0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
16cd0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
16ce0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
16cf0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
16d00 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
16d10 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16d20 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
16d30 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16d40 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
16d50 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
16d60 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
16d70 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
16d80 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
16d90 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
16da0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
16db0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16dc0 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
16dd0 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
16de0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16df0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
16e00 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
16e10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
16e20 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
16e30 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
16e40 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
16e50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16e60 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
16e70 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16e80 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
16e90 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
16ea0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
16eb0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
16ec0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
16ed0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
16ee0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16ef0 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
16f00 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
16f10 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
16f20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
16f30 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
16f40 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
16f50 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
16f60 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
16f70 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
16f80 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
16f90 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
16fa0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
16fb0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
16fc0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
16fd0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
16fe0 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
16ff0 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
17000 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
17010 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
17020 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
17030 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
17040 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
17050 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
17060 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
17070 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
17080 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
17090 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
170a0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
170b0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
170c0 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
170d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
170e0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
170f0 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
17100 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
17110 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
17120 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
17130 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
17140 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
17150 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
17160 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
17170 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
17180 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
17190 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
171a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
171b0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
171c0 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
171d0 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
171e0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
171f0 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
17200 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
17210 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
17220 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
17230 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
17240 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
17250 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
17260 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
17270 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17280 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
17290 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
172a0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
172b0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
172c0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
172d0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
172e0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
172f0 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
17300 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
17310 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
17320 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
17330 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
17340 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
17350 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
17360 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
17370 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
17380 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
17390 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
173a0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
173b0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
173c0 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
173d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
173e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
173f0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17400 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17410 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17420 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
17430 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
17440 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
17450 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
17460 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
17470 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
17480 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
17490 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
174a0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
174b0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
174c0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
174d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
174e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
174f0 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
17500 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17510 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17520 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17530 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
17540 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
17550 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
17560 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17570 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17580 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17590 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
175a0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
175b0 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
175c0 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
175d0 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
175e0 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
175f0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17600 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
17610 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17620 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17630 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17640 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17650 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17660 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17670 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
17680 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
17690 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
176a0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
176b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
176c0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
176d0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
176e0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
176f0 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
17700 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17710 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17720 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
17730 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
17740 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
17750 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
17760 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
17770 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
17780 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
17790 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
177a0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
177b0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
177c0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
177d0 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
177e0 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
177f0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
17800 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
17810 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
17820 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
17830 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
17840 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
17850 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
17860 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
17870 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
17880 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
17890 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
178a0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
178b0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
178c0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
178d0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
178e0 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
178f0 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
17900 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17910 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
17920 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
17930 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
17940 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
17950 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
17960 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
17970 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  e3.**.** ^Each e
17980 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
17990 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
179a0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
179b0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
179c0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
179d0 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
179e0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
179f0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
17a00 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
17a10 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
17a20 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
17a30 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
17a40 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
17a50 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
17a60 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
17a70 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
17a80 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
17a90 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
17aa0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
17ab0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
17ac0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
17ad0 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
17ae0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
17af0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
17b00 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
17b10 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
17b20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
17b30 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17b40 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72  d(D) interface r
17b50 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
17b60 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f  d] of the .** mo
17b70 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
17b80 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
17b90 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
17ba0 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
17bb0 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
17bc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
17bd0 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74  .** ^Inserts int
17be0 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
17bf0 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
17c00 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49   recorded..** ^I
17c10 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
17c20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
17c30 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68  owid tables.** h
17c40 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
17c50 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  d on the databas
17c60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  e connection D, 
17c70 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
17c80 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
17c90 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65  id(D) returns ze
17ca0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ro..**.** ^(If a
17cb0 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
17cc0 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
17cd0 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
17ce0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
17cf0 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
17d00 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
17d10 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
17d20 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
17d30 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
17d40 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
17d50 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
17d60 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
17d70 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
17d80 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
17d90 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
17da0 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
17db0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
17dc0 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
17dd0 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
17de0 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
17df0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
17e00 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
17e10 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
17e20 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
17e30 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
17e40 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
17e50 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
17e60 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
17e70 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
17e80 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
17e90 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17ea0 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
17eb0 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
17ec0 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
17ed0 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
17ee0 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
17ef0 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
17f00 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
17f10 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
17f20 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
17f30 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
17f40 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
17f50 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
17f60 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
17f70 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
17f80 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
17f90 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
17fa0 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
17fb0 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
17fc0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
17fd0 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
17fe0 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
17ff0 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
18000 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
18010 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
18020 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
18030 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
18040 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
18050 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
18060 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
18070 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
18080 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
18090 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
180a0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
180b0 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
180c0 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
180d0 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
180e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
180f0 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
18100 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
18110 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
18120 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
18130 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
18140 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
18150 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
18160 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
18170 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
18180 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
18190 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
181a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
181b0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
181c0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
181d0 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
181e0 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
181f0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
18200 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
18210 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
18220 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
18230 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
18240 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
18250 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
18260 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
18270 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
18280 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
18290 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
182a0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
182b0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
182c0 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
182d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
182e0 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
182f0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
18300 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
18310 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
18320 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
18330 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
18340 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20   rows modified, 
18350 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64  inserted or.** d
18360 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
18370 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
18380 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
18390 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a  DATE or DELETE.*
183a0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74  * statement on t
183b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
183c0 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  ection specified
183d0 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   by the only par
183e0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63  ameter..** ^Exec
183f0 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
18400 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
18410 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d  ement does not m
18420 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a  odify the value.
18430 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ** returned by t
18440 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
18450 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65  .** ^Only change
18460 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20  s made directly 
18470 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
18480 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
18490 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a  statement are.**
184a0 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75   considered - au
184b0 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
184c0 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54  caused by [CREAT
184d0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
184e0 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65  gers], .** [fore
184f0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
18500 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   or [REPLACE] co
18510 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
18520 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ion are not coun
18530 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e  ted..** .** Chan
18540 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
18550 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
18560 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45  ed by .** [INSTE
18570 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20  AD OF trigger | 
18580 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
18590 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ers] are not cou
185a0 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65  nted. ^The value
185b0 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79   .** returned by
185c0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
185d0 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  () immediately a
185e0 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20  fter an INSERT, 
185f0 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45  UPDATE or .** DE
18600 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72  LETE statement r
18610 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20  un on a view is 
18620 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c  always zero. Onl
18630 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74  y changes made t
18640 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65  o real .** table
18650 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
18660 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20  *.** Things are 
18670 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64  more complicated
18680 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
18690 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
186a0 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65  on is.** execute
186b0 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65  d while a trigge
186c0 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e  r program is run
186d0 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68  ning. This may h
186e0 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20  appen if the.** 
186f0 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65  program uses the
18700 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
18710 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66  function], or if
18720 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c   some other call
18730 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
18740 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33   invokes sqlite3
18750 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63  _changes() direc
18760 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79  tly. Essentially
18770 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
18780 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65     <li> ^(Before
18790 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67   entering a trig
187a0 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20  ger program the 
187b0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
187c0 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69  y.**        sqli
187d0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
187e0 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e  nction is saved.
187f0 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67   After the trigg
18800 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20  er program .**  
18810 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68        has finish
18820 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ed, the original
18830 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72   value is restor
18840 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c  ed.)^.** .**   <
18850 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74  li> ^(Within a t
18860 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
18870 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ach INSERT, UPDA
18880 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a  TE and DELETE .*
18890 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65  *        stateme
188a0 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75  nt sets the valu
188b0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
188c0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
188d0 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20  .**        upon 
188e0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f  completion as no
188f0 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c  rmal. Of course,
18900 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c   this value will
18910 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a   not include .**
18920 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e          any chan
18930 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ges performed by
18940 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61   sub-triggers, a
18950 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  s the sqlite3_ch
18960 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
18970 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65     value will be
18980 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f   saved and resto
18990 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73  red after each s
189a0 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72  ub-trigger has r
189b0 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  un.)^.** </ul>.*
189c0 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e  * .** ^This mean
189d0 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68  s that if the ch
189e0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
189f0 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72  tion (or similar
18a00 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20  ) is used.** by 
18a10 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54  the first INSERT
18a20 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
18a30 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
18a40 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69  hin a trigger, i
18a50 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  t .** returns th
18a60 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77  e value as set w
18a70 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  hen the calling 
18a80 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20  statement began 
18a90 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49  executing..** ^I
18aa0 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20  f it is used by 
18ab0 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75  the second or su
18ac0 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74  bsequent such st
18ad0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
18ae0 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f   trigger .** pro
18af0 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20  gram, the value 
18b00 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74  returned reflect
18b10 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
18b20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79  rows modified by
18b30 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75   the .** previou
18b40 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  s INSERT, UPDATE
18b50 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
18b60 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
18b70 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
18b80 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
18b90 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
18ba0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
18bb0 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
18bc0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
18bd0 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
18be0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18bf0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
18c00 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
18c10 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
18c20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
18c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
18c40 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
18c50 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
18c60 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
18c70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
18c80 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
18c90 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
18ca0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
18cb0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
18cc0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18cd0 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
18ce0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
18cf0 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
18d00 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
18d10 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
18d20 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
18d30 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
18d40 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
18d50 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
18d60 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
18d70 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
18d80 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
18d90 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
18da0 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
18db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
18dc0 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
18dd0 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
18de0 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
18df0 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
18e00 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
18e10 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
18e20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
18e30 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
18e40 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
18e50 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
18e60 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
18e70 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
18e80 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
18e90 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
18ea0 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
18eb0 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
18ec0 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
18ed0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
18ee0 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
18ef0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
18f00 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
18f10 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
18f20 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
18f30 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
18f40 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
18f50 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
18f60 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
18f70 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
18f80 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
18f90 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
18fa0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
18fb0 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
18fc0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18fd0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
18fe0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
18ff0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
19000 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
19010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
19020 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
19030 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
19040 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
19050 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
19060 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
19070 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
19080 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
19090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
190a0 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
190b0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
190c0 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
190d0 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
190e0 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Query.** METHOD:
190f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
19100 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
19110 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
19120 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
19130 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
19140 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
19150 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
19160 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
19170 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
19180 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
19190 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
191a0 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
191b0 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
191c0 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
191d0 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
191e0 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
191f0 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
19200 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
19210 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
19220 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
19230 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
19240 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
19250 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
19260 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
19270 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
19280 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
19290 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
192a0 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
192b0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
192c0 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
192d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
192e0 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
192f0 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
19300 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
19310 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
19320 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
19330 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
19340 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
19350 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
19360 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
19370 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19380 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
19390 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
193a0 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
193b0 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
193c0 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
193d0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
193e0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
193f0 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
19400 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
19410 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
19420 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
19430 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
19440 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
19450 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
19460 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
19470 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
19480 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
19490 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
194a0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
194b0 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
194c0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
194d0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
194e0 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
194f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
19500 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
19510 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
19520 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
19530 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
19540 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
19550 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19560 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
19570 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
19580 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
19590 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
195a0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
195b0 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
195c0 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
195d0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
195e0 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
195f0 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
19600 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
19610 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
19620 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
19630 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
19640 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
19650 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
19660 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
19670 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
19680 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
19690 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
196a0 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
196b0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
196c0 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
196d0 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
196e0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
196f0 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
19700 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
19710 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
19720 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
19730 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
19740 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
19750 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
19760 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
19770 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
19780 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
19790 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
197a0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
197b0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
197c0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
197d0 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
197e0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
197f0 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
19800 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
19810 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
19820 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
19830 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19840 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
19850 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
19860 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
19870 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
19880 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
19890 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
198a0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
198b0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
198c0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
198d0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
198e0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
198f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
19900 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
19910 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
19920 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
19930 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
19940 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
19950 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
19960 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
19970 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
19980 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
19990 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
199a0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
199b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
199c0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
199d0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
199e0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
199f0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
19a00 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
19a10 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
19a20 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
19a30 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
19a40 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
19a50 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
19a60 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
19a70 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
19a80 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
19a90 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
19aa0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
19ab0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
19ac0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
19ad0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
19ae0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
19af0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
19b00 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
19b10 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
19b20 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
19b30 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
19b40 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
19b50 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
19b60 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
19b70 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
19b80 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
19b90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
19ba0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
19bb0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
19bc0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
19bd0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
19be0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
19bf0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
19c00 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
19c10 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
19c20 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
19c30 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
19c40 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
19c50 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
19c60 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
19c70 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
19c80 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
19c90 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
19ca0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
19cb0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
19cc0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
19cd0 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
19ce0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
19cf0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
19d00 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
19d10 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
19d20 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
19d30 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
19d40 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
19d50 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
19d60 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
19d70 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
19d80 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
19d90 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
19da0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
19db0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
19dc0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
19dd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
19de0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
19df0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
19e00 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
19e10 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
19e20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
19e30 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
19e40 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
19e50 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
19e60 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
19e70 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
19e80 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
19e90 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
19ea0 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
19eb0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
19ec0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
19ed0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
19ee0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
19ef0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
19f00 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
19f10 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75  ** KEYWORDS: {bu
19f20 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
19f30 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c  ack} {busy handl
19f40 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
19f50 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
19f60 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
19f70 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f  andler(D,X,P) ro
19f80 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
19f90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
19fa0 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62  .** that might b
19fb0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
19fc0 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
19fd0 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
19fe0 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
19ff0 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61  ss a database ta
1a000 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  ble associated w
1a010 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ith.** [database
1a020 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
1a030 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hen another thre
1a040 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
1a050 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c   has the table l
1a060 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71  ocked..** The sq
1a070 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1a080 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  er() interface i
1a090 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
1a0a0 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ent.** [sqlite3_
1a0b0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
1a0c0 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79  and [PRAGMA busy
1a0d0 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a  _timeout]..**.**
1a0e0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1a0f0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
1a100 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
1a110 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  Y].** is returne
1a120 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
1a130 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
1a140 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
1a150 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1a160 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
1a170 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
1a180 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
1a190 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
1a1a0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
1a1b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1a1c0 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
1a1d0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
1a1e0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
1a1f0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
1a200 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
1a210 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
1a220 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
1a230 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
1a240 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
1a250 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
1a260 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
1a270 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
1a280 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1a290 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
1a2a0 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79  voked previously
1a2b0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
1a2c0 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
1a2d0 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
1a2e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
1a2f0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
1a300 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
1a310 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
1a320 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1a330 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
1a340 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a  Y] is returned.*
1a350 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1a360 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
1a370 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1a380 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
1a390 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
1a3a0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61  .** is made to a
1a3b0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1a3c0 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  se and the cycle
1a3d0 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
1a3e0 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
1a3f0 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
1a400 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
1a410 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
1a420 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
1a430 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
1a440 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
1a450 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
1a460 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
1a470 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
1a480 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
1a490 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
1a4a0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
1a4b0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
1a4c0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20  ITE_BUSY].** to 
1a4d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1a4e0 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
1a4f0 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79  ing the .** busy
1a500 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
1a510 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
1a520 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
1a530 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1a540 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
1a550 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
1a560 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
1a570 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
1a580 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
1a590 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1a5a0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1a5b0 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
1a5c0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
1a5d0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
1a5e0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
1a5f0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
1a600 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
1a610 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1a620 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
1a630 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
1a640 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
1a650 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
1a660 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1a670 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
1a680 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
1a690 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
1a6a0 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
1a6b0 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
1a6c0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
1a6d0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
1a6e0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
1a6f0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
1a700 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
1a710 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
1a720 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
1a730 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1a740 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
1a750 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
1a760 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
1a770 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
1a780 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
1a790 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
1a7a0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
1a7b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1a7c0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1a7d0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1a7e0 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
1a7f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1a800 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
1a810 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
1a820 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
1a830 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
1a840 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
1a850 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
1a860 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1a870 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f  _timeout()].** o
1a880 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52  r evaluating [PR
1a890 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1a8a0 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65  t=N] will change
1a8b0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
1a8c0 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c  dler and thus cl
1a8d0 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ear any previous
1a8e0 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64  ly set busy hand
1a8f0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
1a900 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
1a910 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
1a920 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
1a930 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
1a940 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a950 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1a960 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
1a970 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
1a980 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1a990 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e  dler is not reen
1a9a0 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68  trant.  Any such
1a9b0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
1a9c0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
1a9d0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
1a9e0 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
1a9f0 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
1aa00 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1aa10 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
1aa20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1aa30 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
1aa40 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1aa50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1aa60 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
1aa70 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
1aa80 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
1aa90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1aaa0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
1aab0 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meout.** METHOD:
1aac0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1aad0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1aae0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1aaf0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1ab00 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1ab10 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1ab20 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1ab30 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1ab40 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1ab50 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1ab60 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1ab70 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1ab80 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1ab90 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1aba0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1abb0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1abc0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1abd0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1abe0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1abf0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1ac00 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1ac10 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1ac20 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1ac30 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
1ac40 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1ac50 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1ac60 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1ac70 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1ac80 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1ac90 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1aca0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1acb0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1acc0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1acd0 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1ace0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1acf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ad00 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d  ] at any given m
1ad10 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
1ad20 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
1ad30 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
1ad40 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
1ad50 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
1ad60 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
1ad70 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
1ad80 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
1ad90 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
1ada0 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  eared.)^.**.** S
1adb0 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d  ee also:  [PRAGM
1adc0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a  A busy_timeout].
1add0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1ade0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1adf0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1ae00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ae10 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1ae20 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1ae30 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48   Queries.** METH
1ae40 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1ae50 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
1ae60 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
1ae70 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
1ae80 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1ae90 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
1aea0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
1aeb0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
1aec0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
1aed0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
1aee0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
1aef0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
1af00 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
1af10 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
1af20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1af30 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
1af40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
1af50 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
1af60 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
1af70 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
1af80 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
1af90 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
1afa0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
1afb0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
1afc0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
1afd0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
1afe0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
1aff0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1b000 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
1b010 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
1b020 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
1b030 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
1b040 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1b050 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
1b060 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1b070 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
1b080 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
1b090 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
1b0a0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
1b0b0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1b0c0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
1b0d0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
1b0e0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
1b0f0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
1b100 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
1b110 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1b120 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1b130 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
1b140 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
1b150 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
1b160 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
1b170 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
1b180 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
1b190 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
1b1a0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
1b1b0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
1b1c0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
1b1d0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1b1e0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1b1f0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
1b200 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1b210 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1b220 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
1b230 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
1b240 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
1b250 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
1b260 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
1b270 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
1b280 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
1b290 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
1b2a0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1b2b0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
1b2c0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
1b2d0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
1b2e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
1b2f0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
1b300 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
1b310 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1b320 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
1b330 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
1b340 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
1b350 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1b360 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b370 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
1b380 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
1b390 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
1b3a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
1b3b0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
1b3c0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
1b3d0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
1b3e0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
1b3f0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
1b400 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b410 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
1b420 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
1b430 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
1b440 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
1b450 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
1b460 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
1b470 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
1b480 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1b490 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1b4a0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
1b4b0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
1b4c0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
1b4d0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
1b4e0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b4f0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
1b500 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
1b510 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
1b520 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
1b530 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
1b540 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b550 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
1b560 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b570 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
1b580 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b590 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
1b5a0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
1b5b0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
1b5c0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
1b5d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
1b5e0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
1b5f0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b600 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
1b610 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b620 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
1b630 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b640 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
1b650 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
1b660 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
1b670 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
1b680 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1b690 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b6a0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
1b6b0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
1b6c0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
1b6d0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1b6e0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
1b6f0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
1b700 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
1b710 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
1b720 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
1b730 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
1b740 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
1b750 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b760 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
1b770 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
1b780 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
1b790 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1b7a0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
1b7b0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
1b7c0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
1b7d0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
1b7e0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
1b7f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
1b800 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
1b810 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
1b820 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
1b830 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
1b840 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
1b850 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
1b860 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
1b870 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
1b880 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1b890 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
1b8a0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1b8b0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
1b8c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
1b8d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b8e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1b8f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
1b900 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
1b910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1b920 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
1b930 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
1b940 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
1b950 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
1b960 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
1b970 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
1b980 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
1b990 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
1b9a0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
1b9b0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
1b9c0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
1b9d0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
1b9e0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
1b9f0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
1ba00 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
1ba10 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
1ba20 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
1ba30 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
1ba40 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1ba50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
1ba60 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
1ba70 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1ba80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1ba90 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
1baa0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1bab0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
1bac0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
1bad0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1bae0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
1baf0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
1bb00 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
1bb10 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
1bb20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
1bb30 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
1bb40 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1bb50 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
1bb60 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1bb70 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
1bb80 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
1bb90 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
1bba0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
1bbb0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
1bbc0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
1bbd0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
1bbe0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
1bbf0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1bc00 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1bc10 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1bc20 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1bc30 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1bc40 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1bc50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1bc60 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1bc70 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1bc80 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1bc90 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1bca0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1bcb0 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1bcc0 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1bcd0 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1bce0 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1bcf0 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
1bd00 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1bd10 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1bd20 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
1bd30 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
1bd40 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
1bd50 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
1bd60 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1bd70 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
1bd80 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
1bd90 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
1bda0 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
1bdb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
1bdc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1bdd0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1bde0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1bdf0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1be00 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1be10 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1be20 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1be30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1be40 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1be50 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1be60 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1be70 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1be80 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1be90 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1bea0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1beb0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1bec0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1bed0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1bee0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1bef0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1bf00 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1bf10 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1bf20 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1bf30 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1bf40 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1bf50 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1bf60 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1bf70 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1bf80 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1bf90 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1bfa0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1bfb0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1bfc0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1bfd0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1bfe0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1bff0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1c000 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1c010 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1c020 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1c030 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1c040 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1c050 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1c060 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1c070 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1c080 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1c090 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1c0a0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1c0b0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1c0c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1c0d0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1c0e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1c0f0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1c100 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1c110 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1c120 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1c130 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1c140 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1c150 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1c160 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1c170 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1c180 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1c190 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1c1a0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1c1b0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1c1c0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1c1d0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1c1e0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1c1f0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1c200 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1c210 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1c220 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1c230 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1c240 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1c250 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1c260 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1c270 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1c280 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1c290 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1c2a0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1c2b0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1c2c0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1c2d0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1c2e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1c2f0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1c300 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1c310 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1c320 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1c330 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1c340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c350 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1c360 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1c370 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1c380 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1c390 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1c3a0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1c3b0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1c3c0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1c3d0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1c3e0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1c3f0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1c400 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1c410 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1c420 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1c430 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1c440 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1c450 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1c460 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
1c470 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
1c480 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1c490 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1c4a0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1c4b0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1c4c0 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1c4d0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1c4e0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1c4f0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1c500 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1c510 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1c520 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1c530 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1c540 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1c550 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1c560 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1c570 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1c580 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1c590 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1c5a0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1c5b0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1c5c0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1c5d0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1c5e0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1c5f0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1c600 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1c610 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c620 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1c630 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1c640 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1c650 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c660 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1c670 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1c680 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1c690 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1c6a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1c6b0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1c6c0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1c6d0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1c6e0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1c6f0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1c700 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1c710 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1c720 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1c730 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1c740 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1c750 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1c760 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1c770 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1c780 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1c790 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1c7a0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1c7b0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1c7c0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1c7d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1c7e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c7f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1c800 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1c810 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1c820 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c830 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1c840 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1c850 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1c860 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1c870 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1c880 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1c890 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1c8a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c8b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1c8c0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1c8d0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1c8e0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1c8f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1c900 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1c910 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1c920 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1c930 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1c940 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1c950 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1c960 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1c970 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1c980 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1c990 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1c9a0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1c9b0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1c9c0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1c9d0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1c9e0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1c9f0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1ca00 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1ca10 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1ca20 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1ca30 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1ca40 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1ca50 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1ca60 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1ca70 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1ca80 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1ca90 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1caa0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1cab0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1cac0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1cad0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1cae0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1caf0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1cb00 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1cb10 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1cb20 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1cb30 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1cb40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1cb50 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1cb60 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1cb70 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1cb80 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1cb90 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1cba0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1cbb0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1cbc0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1cbd0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1cbe0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1cbf0 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
1cc00 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1cc10 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
1cc20 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
1cc30 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
1cc40 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
1cc50 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
1cc60 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
1cc70 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
1cc80 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
1cc90 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
1cca0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
1ccb0 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
1ccc0 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
1ccd0 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1cce0 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
1ccf0 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
1cd00 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
1cd10 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
1cd20 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
1cd30 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
1cd40 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
1cd50 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1cd60 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1cd70 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1cd80 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1cd90 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1cda0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1cdb0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1cdc0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1cdd0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1cde0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1cdf0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1ce00 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1ce10 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1ce20 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1ce30 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1ce40 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1ce50 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1ce60 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1ce70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1ce80 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1ce90 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1cea0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1ceb0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1cec0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1ced0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1cee0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1cef0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1cf00 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1cf10 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1cf20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1cf30 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1cf40 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1cf50 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1cf60 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1cf70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1cf80 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1cf90 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1cfa0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1cfb0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1cfc0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1cfd0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1cfe0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1cff0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1d000 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1d010 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1d020 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1d030 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1d040 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1d050 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1d060 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1d070 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1d080 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1d090 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1d0a0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1d0b0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1d0c0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1d0d0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1d0e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1d0f0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1d100 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1d110 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1d120 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1d130 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1d140 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1d150 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1d160 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
1d170 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e  lite3_malloc64(N
1d180 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20  ) routine works 
1d190 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c  just like.** sql
1d1a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65  ite3_malloc(N) e
1d1b0 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1d1c0 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62  an unsigned 64-b
1d1d0 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  it integer inste
1d1e0 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65  ad.** of a signe
1d1f0 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  d 32-bit integer
1d200 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1d210 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1d220 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1d230 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1d240 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1d250 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1d260 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1d270 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1d280 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1d290 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1d2a0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1d2b0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1d2c0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1d2d0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1d2e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1d2f0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1d300 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1d310 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1d320 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1d330 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1d340 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1d350 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1d360 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1d370 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1d380 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1d390 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1d3a0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1d3b0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1d3c0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1d3d0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1d3e0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1d3f0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1d400 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1d410 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1d420 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1d430 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1d440 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1d450 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1d460 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1d470 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1d480 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1d490 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1d4a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1d4b0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65  ealloc(X,N) inte
1d4c0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1d4d0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1d4e0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1d4f0 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74  ation X to be at
1d500 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a   least N bytes..
1d510 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72  ** ^If the X par
1d520 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1d530 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a  3_realloc(X,N).*
1d540 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
1d550 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
1d560 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
1d570 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
1d580 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d590 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  N)..** ^If the N
1d5a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1d5b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d5c0 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  N) is zero or.**
1d5d0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1d5e0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1d5f0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1d600 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1d610 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a  lite3_free(X)..*
1d620 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1d630 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1d640 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1d650 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d660 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1d670 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1d680 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  or NULL if insuf
1d690 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1d6a0 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
1d6b0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1d6c0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1d6d0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1d6e0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1d6f0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1d700 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1d710 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1d720 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1d730 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1d740 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d750 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72  (X,N) and the pr
1d760 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1d770 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1d780 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d790 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  X,N) returns NUL
1d7a0 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74  L and N is posit
1d7b0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ive, then the.**
1d7c0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1d7d0 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  n is not freed..
1d7e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d7f0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e  e3_realloc64(X,N
1d800 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  ) interfaces wor
1d810 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ks the same as.*
1d820 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * sqlite3_reallo
1d830 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68  c(X,N) except th
1d840 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74  at N is a 64-bit
1d850 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
1d860 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1d870 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  a 32-bit signed 
1d880 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1d890 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79  If X is a memory
1d8a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76   allocation prev
1d8b0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
1d8c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1d8d0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1d8e0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71  3_malloc64(), sq
1d8f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1d900 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1d910 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a  loc64(), then.**
1d920 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d930 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  ) returns the si
1d940 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72  ze of that memor
1d950 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20  y allocation in 
1d960 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76  bytes..** ^The v
1d970 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1d980 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d990 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  ) might be large
1d9a0 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65  r than the numbe
1d9b0 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65  r.** of bytes re
1d9c0 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77  quested when X w
1d9d0 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  as allocated.  ^
1d9e0 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70  If X is a NULL p
1d9f0 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73  ointer then.** s
1da00 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1da10 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49  returns zero.  I
1da20 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f  f X points to so
1da30 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20  mething that is 
1da40 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e  not.** the begin
1da50 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ning of memory a
1da60 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66  llocation, or if
1da70 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20   it points to a 
1da80 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69  formerly.** vali
1da90 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
1daa0 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77  ion that has now
1dab0 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65   been freed, the
1dac0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
1dad0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69  * of sqlite3_msi
1dae0 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e  ze(X) is undefin
1daf0 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ed and possibly 
1db00 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
1db10 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1db20 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1db30 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33  alloc(), sqlite3
1db40 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  _realloc(),.** s
1db50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1db60 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
1db70 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73  ealloc64().** is
1db80 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
1db90 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
1dba0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
1dbb0 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
1dbc0 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
1dbd0 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
1dbe0 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
1dbf0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1dc00 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
1dc10 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
1dc20 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
1dc30 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
1dc40 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
1dc50 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
1dc60 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
1dc70 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
1dc80 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
1dc90 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
1dca0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
1dcb0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
1dcc0 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
1dcd0 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
1dce0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
1dcf0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
1dd00 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1dd10 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
1dd20 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
1dd30 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1dd40 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
1dd50 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
1dd60 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
1dd70 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1dd80 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1dd90 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1dda0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1ddb0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1ddc0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1ddd0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1dde0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1ddf0 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1de00 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1de10 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1de20 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1de30 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1de40 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1de50 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
1de60 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
1de70 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1de80 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1de90 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1dea0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1deb0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1dec0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1ded0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1dee0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1def0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1df00 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1df10 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1df20 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1df30 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1df40 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1df50 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1df60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1df70 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1df80 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1df90 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1dfa0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1dfb0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1dfc0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1dfd0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1dfe0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1dff0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1e000 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1e010 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1e020 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1e030 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1e040 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
1e050 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1e060 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1e070 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1e080 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1e090 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1e0a0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
1e0b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1e0c0 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
1e0d0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1e0e0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1e0f0 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  void*);.sqlite3_
1e100 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
1e110 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
1e120 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1e130 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1e140 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1e150 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1e160 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1e170 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1e180 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1e190 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1e1a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1e1b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1e1c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1e1d0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1e1e0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1e1f0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1e200 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1e210 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1e220 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1e230 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1e240 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1e250 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1e260 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1e270 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1e280 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1e290 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1e2a0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1e2b0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1e2c0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1e2d0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1e2e0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1e2f0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1e300 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1e310 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1e320 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1e330 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1e340 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1e350 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1e360 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1e370 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1e380 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1e390 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1e3a0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1e3b0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1e3c0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1e3d0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1e3e0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1e3f0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1e400 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1e410 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1e420 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1e430 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1e440 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1e450 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1e460 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1e470 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1e480 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1e490 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1e4a0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1e4b0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1e4c0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1e4d0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1e4e0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1e4f0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1e500 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1e510 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e520 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1e530 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1e540 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1e550 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
1e560 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1e570 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1e580 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
1e590 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1e5a0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1e5b0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1e5c0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1e5d0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1e5e0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1e5f0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1e600 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1e610 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1e620 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1e630 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1e640 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1e650 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1e660 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1e670 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1e680 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1e690 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1e6a0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1e6b0 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1e6c0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1e6d0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1e6e0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1e6f0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1e700 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1e710 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1e720 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1e730 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1e740 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1e750 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1e760 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1e770 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1e780 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1e790 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1e7a0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68  buffer P..** ^Th
1e7b0 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61  e P parameter ca
1e7c0 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
1e7d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
1e7e0 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
1e7f0 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
1e800 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
1e810 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
1e820 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
1e830 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e   than one or a N
1e840 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
1e850 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47  P, then the PRNG
1e860 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73   is.** seeded us
1e870 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
1e880 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65  btained from the
1e890 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
1e8a0 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65  hod of.** the de
1e8b0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1e8c0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
1e8d0 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
1e8e0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1e8f0 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
1e900 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61   1 or more and a
1e910 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74  .** non-NULL P t
1e920 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72  hen the pseudo-r
1e930 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1e940 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1e950 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1e960 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1e970 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1e980 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1e990 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
1e9a0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1e9b0 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1e9c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e9d0 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1e9e0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1e9f0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
1ea00 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1ea10 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1ea20 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1ea30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ea40 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1ea50 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1ea60 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1ea70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1ea80 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1ea90 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1eaa0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1eab0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1eac0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1ead0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1eae0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1eaf0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1eb00 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1eb10 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1eb20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1eb30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1eb40 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1eb50 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1eb60 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1eb70 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1eb80 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1eb90 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1eba0 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1ebb0 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1ebc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ebd0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1ebe0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1ebf0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1ec00 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1ec10 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ec20 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1ec30 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1ec40 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1ec50 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1ec60 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1ec70 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1ec80 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1ec90 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1eca0 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1ecb0 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1ecc0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1ecd0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1ece0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1ecf0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1ed00 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1ed10 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1ed20 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ed30 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1ed40 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1ed50 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1ed60 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1ed70 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1ed80 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1ed90 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1eda0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1edb0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1edc0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1edd0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1ede0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1edf0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1ee00 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1ee10 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1ee20 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1ee30 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1ee40 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1ee50 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1ee60 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1ee70 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1ee80 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1ee90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1eea0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1eeb0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1eec0 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1eed0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1eee0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1eef0 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1ef00 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1ef10 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1ef20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1ef30 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1ef40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ef50 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1ef60 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1ef70 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1ef80 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1ef90 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1efa0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1efb0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1efc0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1efd0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1efe0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1eff0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1f000 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1f010 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1f020 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1f030 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1f040 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1f050 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1f060 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1f070 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1f080 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1f090 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1f0a0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1f0b0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1f0c0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1f0d0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1f0e0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1f0f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1f100 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1f110 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1f120 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1f130 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1f140 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1f150 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1f160 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1f170 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1f180 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1f190 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1f1a0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1f1b0 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1f1c0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1f1d0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1f1e0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1f1f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1f200 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1f210 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1f220 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1f230 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1f240 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1f250 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1f260 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1f270 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1f280 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1f290 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1f2a0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1f2b0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1f2c0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1f2d0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1f2e0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1f2f0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1f300 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1f310 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1f320 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1f330 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1f340 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1f350 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1f360 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1f370 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1f380 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1f390 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1f3a0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1f3b0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1f3c0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1f3d0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1f3e0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1f3f0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1f400 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1f410 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1f420 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1f430 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1f440 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1f450 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1f460 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1f470 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1f480 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1f490 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1f4a0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1f4b0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1f4c0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1f4d0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1f4e0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1f4f0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1f500 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1f510 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1f520 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1f530 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1f540 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1f550 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1f560 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1f570 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1f580 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1f590 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1f5a0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1f5b0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1f5c0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1f5d0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1f5e0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1f5f0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1f600 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1f610 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1f620 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1f630 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1f640 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1f650 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1f660 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1f670 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1f680 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1f690 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1f6a0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1f6b0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1f6c0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1f6d0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1f6e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1f6f0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1f700 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1f710 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1f720 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1f730 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1f740 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1f750 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1f760 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1f770 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1f780 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1f790 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1f7a0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1f7b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f7c0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1f7d0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1f7e0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1f7f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f800 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1f810 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1f820 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1f830 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1f840 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1f850 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f860 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1f870 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1f880 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1f890 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1f8a0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1f8b0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1f8c0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1f8d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1f8e0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1f8f0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1f900 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1f910 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1f920 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1f930 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1f940 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1f950 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1f960 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1f970 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1f980 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1f990 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1f9a0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1f9b0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1f9c0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1f9d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1f9e0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1f9f0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1fa00 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1fa10 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1fa20 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1fa30 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1fa40 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1fa50 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1fa60 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1fa70 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1fa80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1fa90 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1faa0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1fab0 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1fac0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1fad0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1fae0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1faf0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1fb00 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1fb10 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1fb20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1fb30 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1fb40 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1fb50 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1fb60 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1fb70 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1fb80 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1fb90 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1fba0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1fbb0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1fbc0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1fbd0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1fbe0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1fbf0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1fc00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1fc10 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1fc20 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1fc30 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1fc40 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1fc50 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1fc60 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1fc70 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1fc80 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1fc90 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1fca0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1fcb0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1fcc0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1fcd0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1fce0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1fcf0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1fd00 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1fd10 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1fd20 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
1fd30 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
1fd40 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
1fd50 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1fd60 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1fd70 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1fd80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fd90 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1fda0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1fdb0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1fdc0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1fdd0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1fde0 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1fdf0 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1fe00 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1fe10 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1fe20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1fe30 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1fe40 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1fe50 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1fe60 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1fe70 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1fe80 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1fe90 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1fea0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1feb0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1fec0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1fed0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1fee0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1fef0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1ff00 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1ff10 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1ff20 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1ff30 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1ff40 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1ff50 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1ff60 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1ff70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ff80 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1ff90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1ffa0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1ffb0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1ffc0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1ffd0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1ffe0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1fff0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
20000 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
20010 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
20020 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
20030 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
20040 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
20050 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
20060 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
20070 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
20080 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
20090 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
200a0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
200b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
200c0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
200d0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
200e0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
200f0 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
20100 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
20110 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20120 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20130 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
20140 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
20150 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
20160 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
20170 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
20180 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
20190 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
201a0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
201b0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
201c0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
201d0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
201e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
201f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20200 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
20210 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
20220 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
20230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
20240 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
20250 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
20260 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
20270 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20280 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20290 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
202a0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
202b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
202c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
202d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
202e0 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
202f0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
20300 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
20310 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
20320 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
20330 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
20340 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
20350 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20360 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20370 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
20380 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
20390 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
203a0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
203b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
203c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
203d0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
203e0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
203f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20400 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20410 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
20420 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
20430 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
20440 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20450 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20460 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
20470 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
20480 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
20490 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
204a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
204b0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
204c0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
204d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
204e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
204f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20500 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
20510 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
20520 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
20530 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20540 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20550 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
20560 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
20570 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20580 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20590 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
205a0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
205b0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
205c0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
205d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
205e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
205f0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
20600 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
20610 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20620 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20640 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
20650 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
20660 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
20670 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20690 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
206a0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
206b0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
206c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
206d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
206e0 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
206f0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
20700 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
20710 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20730 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
20740 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
20750 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
20760 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20770 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
20780 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
20790 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
207a0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
207b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
207c0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
207d0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
207e0 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
207f0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
20800 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
20810 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
20820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20830 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
20840 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
20850 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
20860 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
20870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
20880 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
20890 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
208a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
208b0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
208c0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
208d0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
208e0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
208f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20900 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
20910 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
20920 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20930 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
20940 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20950 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
20960 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
20970 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
20980 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20990 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
209a0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
209b0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
209c0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
209d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
209e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
209f0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
20a00 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
20a10 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
20a20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20a30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20a40 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
20a50 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
20a60 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
20a70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20a80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20a90 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
20aa0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
20ab0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
20ac0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20ad0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20ae0 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
20af0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
20b00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
20b10 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
20b20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20b30 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
20b40 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
20b50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
20b60 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
20b70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
20b80 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
20b90 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
20ba0 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
20bb0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
20bc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
20bd0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
20be0 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
20bf0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
20c00 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
20c10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
20c20 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
20c30 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
20c40 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
20c50 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
20c60 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
20c70 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
20c80 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
20c90 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
20ca0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
20cb0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
20cc0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
20cd0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
20ce0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
20cf0 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
20d00 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
20d10 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
20d20 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
20d30 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
20d40 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
20d50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
20d60 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
20d70 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
20d80 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
20d90 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
20da0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
20db0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
20dc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
20dd0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
20de0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
20df0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20e00 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
20e10 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
20e20 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
20e30 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
20e40 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
20e50 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
20e60 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
20e70 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
20e80 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
20e90 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
20ea0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
20eb0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
20ec0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
20ed0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
20ee0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
20ef0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
20f00 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
20f10 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
20f20 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
20f30 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
20f40 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
20f50 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
20f60 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
20f70 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
20f80 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
20f90 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
20fa0 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
20fb0 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
20fc0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
20fd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
20fe0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
20ff0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
21000 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
21010 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
21020 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
21030 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
21040 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
21050 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
21060 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
21070 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
21080 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
21090 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
210a0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
210b0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
210c0 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
210d0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
210e0 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
210f0 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
21100 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
21110 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
21120 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
21130 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
21140 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
21150 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
21160 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
21170 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
21180 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
21190 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
211a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
211b0 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
211c0 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
211d0 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
211e0 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
211f0 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
21200 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
21210 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
21220 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
21230 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
21240 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
21250 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
21260 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69  f SQLite..*/.voi
21270 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
21280 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
21290 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
212a0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
212b0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
212c0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
212d0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
212e0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
212f0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
21300 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
21310 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
21320 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
21330 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
21340 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
21350 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
21360 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
21370 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
21380 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
21390 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
213a0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
213b0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
213c0 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
213d0 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
213e0 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
213f0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
21400 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
21410 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
21420 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
21430 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
21440 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21450 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
21460 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
21470 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
21480 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
21490 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
214a0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
214b0 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
214c0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
214d0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
214e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
214f0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
21500 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
21510 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
21520 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
21530 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
21540 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
21550 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
21560 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
21570 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
21580 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
21590 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
215a0 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
215b0 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
215c0 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
215d0 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
215e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
215f0 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
21600 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
21610 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
21620 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
21630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21640 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
21650 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
21660 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
21670 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
21680 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
21690 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
216a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
216b0 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
216c0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
216d0 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
216e0 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
216f0 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
21700 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
21710 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
21720 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
21730 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
21740 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
21750 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
21760 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
21770 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
21780 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
21790 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
217a0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
217b0 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
217c0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
217d0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
217e0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
217f0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
21800 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
21810 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
21820 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
21830 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
21840 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
21850 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21860 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
21870 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
21880 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
21890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
218a0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
218b0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
218c0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
218d0 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
218e0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
218f0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
21900 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
21910 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
21920 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
21930 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
21940 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43   Connection.** C
21950 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
21960 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
21970 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
21980 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
21990 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
219a0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
219b0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
219c0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
219d0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
219e0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
219f0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
21a00 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
21a10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
21a20 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
21a30 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
21a40 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
21a50 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
21a60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
21a70 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
21a80 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
21a90 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
21aa0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
21ab0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
21ac0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
21ad0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
21ae0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
21af0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
21b00 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
21b10 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
21b20 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
21b30 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
21b40 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
21b50 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
21b60 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
21b70 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
21b80 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21b90 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
21ba0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
21bb0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
21bc0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
21bd0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
21be0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
21bf0 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
21c00 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
21c10 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
21c20 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
21c30 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
21c40 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
21c50 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
21c60 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
21c70 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
21c80 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
21c90 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
21ca0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21cb0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
21cc0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
21cd0 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54  oding will be UT
21ce0 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65  F-8 for database
21cf0 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
21d00 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
21d10 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
21d20 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65  n_v2().  ^The de
21d30 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
21d40 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  or databases.** 
21d50 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71  created using sq
21d60 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77  lite3_open16() w
21d70 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e  ill be UTF-16 in
21d80 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
21d90 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68   order..**.** Wh
21da0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
21db0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
21dc0 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
21dd0 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
21de0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
21df0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
21e00 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
21e10 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
21e20 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
21e30 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
21e40 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
21e50 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
21e60 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
21e70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21e80 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
21e90 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
21ea0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
21eb0 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
21ec0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
21ed0 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
21ee0 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
21ef0 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
21f00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21f10 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
21f20 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
21f30 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
21f40 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
21f50 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
21f60 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
21f70 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
21f80 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
21f90 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
21fa0 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
21fb0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
21fc0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
21fd0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
21fe0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
21ff0 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
22000 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
22010 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
22020 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
22030 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
22040 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
22050 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
22060 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
22070 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
22080 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
22090 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
220a0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
220b0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
220c0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
220d0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
220e0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
220f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
22100 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22110 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
22120 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
22130 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
22140 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
22150 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
22160 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
22170 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
22180 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
22190 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
221a0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
221b0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
221c0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
221d0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
221e0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
221f0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
22200 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
22210 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
22220 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
22230 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
22240 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
22250 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
22260 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
22270 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
22280 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
22290 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
222a0 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
222b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
222c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
222d0 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
222e0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
222f0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
22300 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
22310 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
22320 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
22330 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
22340 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
22350 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
22360 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
22370 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
22380 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
22390 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
223a0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
223b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
223c0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
223d0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
223e0 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
223f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22400 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
22410 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
22420 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
22430 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
22440 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
22450 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
22460 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
22470 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
22480 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
22490 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
224a0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
224b0 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
224c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
224d0 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
224e0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
224f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
22500 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
22510 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
22520 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
22530 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
22540 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
22550 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
22560 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22570 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
22580 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
22590 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
225a0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
225b0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
225c0 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
225d0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
225e0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
225f0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
22600 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
22610 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
22620 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
22630 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22640 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
22650 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
22660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
22670 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
22680 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
22690 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
226a0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
226b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
226c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
226d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
226e0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
226f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
22700 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
22710 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
22720 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
22730 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
22740 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
22750 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
22760 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
22770 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22780 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
22790 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
227a0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
227b0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
227c0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
227d0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
227e0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
227f0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
22800 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
22810 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
22820 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
22830 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
22840 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
22850 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
22860 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
22870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22880 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
22890 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
228a0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
228b0 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
228c0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
228d0 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
228e0 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
228f0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
22900 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
22910 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
22920 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
22930 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
22940 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
22950 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
22960 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
22970 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
22980 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
22990 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
229a0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
229b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
229c0 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
229d0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
229e0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
229f0 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
22a00 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
22a10 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
22a20 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
22a30 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
22a40 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
22a50 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
22a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22a70 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
22a80 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
22a90 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
22aa0 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
22ab0 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
22ac0 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
22ad0 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
22ae0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
22af0 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
22b00 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
22b10 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
22b20 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
22b30 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
22b40 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
22b50 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
22b60 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
22b70 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
22b80 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
22b90 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
22ba0 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
22bb0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
22bc0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
22bd0 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
22be0 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
22bf0 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
22c00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
22c10 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
22c20 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
22c30 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
22c40 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
22c50 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
22c60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
22c70 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
22c80 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
22c90 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
22ca0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
22cb0 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
22cc0 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
22cd0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
22ce0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
22cf0 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
22d00 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
22d10 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
22d20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
22d30 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
22d40 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
22d50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
22d60 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
22d70 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
22d80 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
22d90 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
22da0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
22db0 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
22dc0 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
22dd0 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
22de0 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
22df0 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
22e00 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
22e10 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22e20 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
22e30 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
22e40 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
22e50 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
22e60 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
22e70 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
22e80 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
22e90 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
22ea0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
22eb0 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
22ec0 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
22ed0 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
22ee0 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
22ef0 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
22f00 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
22f10 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
22f20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
22f30 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
22f40 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
22f50 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
22f60 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
22f70 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
22f80 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
22f90 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
22fa0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
22fb0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
22fc0 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
22fd0 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
22fe0 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
22ff0 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
23000 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
23010 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
23020 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
23030 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
23040 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
23050 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
23060 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
23070 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
23080 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
23090 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
230a0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
230b0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
230c0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
230d0 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
230e0 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
230f0 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
23100 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
23110 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
23120 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
23130 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
23140 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
23150 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
23160 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
23170 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
23180 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
23190 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
231a0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
231b0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
231c0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
231d0 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
231e0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
231f0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
23200 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
23210 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
23220 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
23230 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
23240 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
23250 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
23260 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
23270 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
23280 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
23290 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
232a0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
232b0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
232c0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
232d0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
232e0 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
232f0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
23300 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
23310 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
23320 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
23330 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
23340 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
23350 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
23360 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
23370 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
23380 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
23390 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
233a0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
233b0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
233c0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
233d0 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
233e0 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
233f0 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
23400 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
23410 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
23420 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
23430 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
23440 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
23450 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
23460 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
23470 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
23480 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
23490 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
234a0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
234b0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
234c0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
234d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
234e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
234f0 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
23500 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
23510 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
23520 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
23530 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
23540 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
23550 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
23560 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
23570 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
23580 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
23590 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
235a0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
235b0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
235c0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
235d0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
235e0 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
235f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
23600 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
23610 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
23620 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
23630 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
23640 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
23650 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
23660 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
23670 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
23680 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
23690 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
236a0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
236b0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
236c0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
236d0 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
236e0 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
236f0 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
23700 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
23710 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
23720 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
23730 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
23740 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
23750 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
23760 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
23770 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
23780 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
23790 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
237a0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
237b0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
237c0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
237d0 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
237e0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
237f0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
23800 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
23810 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
23820 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
23830 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
23840 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
23850 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
23860 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
23870 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
23880 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
23890 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
238a0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
238b0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
238c0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
238d0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
238e0 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
238f0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
23900 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
23910 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
23920 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
23930 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
23940 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
23950 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
23960 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
23970 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
23980 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
23990 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
239a0 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
239b0 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
239c0 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
239d0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
239e0 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
239f0 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
23a00 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
23a10 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
23a20 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
23a30 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
23a40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23a50 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
23a60 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
23a70 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
23a80 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
23a90 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
23aa0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
23ab0 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
23ac0 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
23ad0 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
23ae0 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
23af0 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
23b00 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
23b10 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
23b20 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
23b30 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
23b40 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
23b50 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
23b60 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
23b70 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
23b80 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
23b90 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
23ba0 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
23bb0 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
23bc0 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
23bd0 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
23be0 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
23bf0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
23c00 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
23c10 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
23c20 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
23c30 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
23c40 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
23c50 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
23c60 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
23c70 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
23c80 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
23c90 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
23ca0 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
23cb0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
23cc0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
23cd0 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
23ce0 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
23cf0 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
23d00 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
23d10 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
23d20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
23d30 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
23d40 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
23d50 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
23d60 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
23d70 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
23d80 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
23d90 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
23da0 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
23db0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
23dc0 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
23dd0 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
23de0 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
23df0 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
23e00 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
23e10 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
23e20 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
23e30 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
23e40 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
23e50 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
23e60 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
23e70 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
23e80 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
23e90 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
23ea0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
23eb0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
23ec0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
23ed0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
23ee0 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
23ef0 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
23f00 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
23f10 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
23f20 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
23f30 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
23f40 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
23f50 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
23f60 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
23f70 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
23f80 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
23f90 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
23fa0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
23fb0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
23fc0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
23fd0 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
23fe0 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
23ff0 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
24000 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
24010 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
24020 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
24030 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
24040 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
24050 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
24060 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
24070 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24080 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
24090 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
240a0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
240b0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
240c0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
240d0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
240e0 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
240f0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
24100 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
24110 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24120 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
24130 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
24140 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24150 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
24160 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
24170 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
24180 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
24190 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
241a0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
241b0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
241c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
241d0 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
241e0 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
241f0 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
24200 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
24210 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
24220 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
24230 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
24240 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
24250 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
24260 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
24270 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
24280 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
24290 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
242a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
242b0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
242c0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
242d0 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
242e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
242f0 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
24300 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
24310 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
24320 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
24330 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
24340 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
24350 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
24360 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
24370 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
24380 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
24390 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
243a0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
243b0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
243c0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
243d0 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
243e0 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
243f0 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
24400 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
24410 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
24420 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
24430 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
24440 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
24450 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
24460 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
24470 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
24480 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
24490 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
244a0 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
244b0 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
244c0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
244d0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
244e0 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
244f0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
24500 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
24510 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
24520 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
24530 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
24540 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
24550 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
24560 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
24570 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
24580 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
24590 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
245a0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
245b0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
245c0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
245d0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
245e0 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
245f0 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
24600 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
24610 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
24620 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
24630 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
24640 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
24650 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
24660 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
24670 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
24680 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
24690 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
246a0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
246b0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
246c0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
246d0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
246e0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
246f0 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
24700 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
24710 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
24720 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
24730 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
24740 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
24750 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
24760 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
24770 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
24780 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
24790 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
247a0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
247b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
247c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
247d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
247e0 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
247f0 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
24800 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
24810 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
24820 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
24830 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
24840 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
24850 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
24860 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
24870 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
24880 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
24890 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
248a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
248b0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
248c0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
248d0 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
248e0 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
248f0 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
24900 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
24910 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
24920 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
24930 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
24940 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
24950 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
24960 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
24970 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
24980 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
24990 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
249a0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
249b0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
249c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
249d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
249e0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
249f0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24a00 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
24a10 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
24a20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
24a30 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
24a40 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
24a50 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
24a60 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
24a70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
24a80 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
24a90 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
24aa0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
24ab0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
24ac0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
24ad0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24ae0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
24af0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
24b00 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24b10 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
24b20 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
24b30 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
24b40 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
24b50 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
24b60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
24b70 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
24b80 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
24b90 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
24ba0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
24bb0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
24bc0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
24bd0 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
24be0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
24bf0 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
24c00 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
24c10 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
24c20 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
24c30 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
24c40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
24c50 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
24c60 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
24c70 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
24c80 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
24c90 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
24ca0 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
24cb0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
24cc0 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
24cd0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24ce0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
24cf0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
24d00 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
24d10 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
24d20 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
24d30 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
24d40 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
24d50 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
24d60 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
24d70 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
24d80 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
24d90 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
24da0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
24db0 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
24dc0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
24dd0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
24de0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
24df0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
24e00 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
24e10 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
24e20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
24e30 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
24e40 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
24e50 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
24e60 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
24e70 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
24e80 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
24e90 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
24ea0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24eb0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24ec0 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
24ed0 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
24ee0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
24ef0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24f00 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
24f10 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
24f20 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
24f30 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
24f40 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
24f50 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
24f60 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
24f70 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
24f80 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
24f90 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
24fa0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
24fb0 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
24fc0 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
24fd0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
24fe0 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
24ff0 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
25000 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
25010 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
25020 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
25030 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
25040 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
25050 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
25060 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
25070 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
25080 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
25090 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
250a0 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
250b0 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
250c0 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
250d0 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
250e0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
250f0 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
25100 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
25110 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
25120 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
25130 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
25140 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
25150 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
25160 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
25170 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
25180 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
25190 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
251a0 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
251b0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
251c0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
251d0 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
251e0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
251f0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
25200 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
25210 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
25220 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
25230 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
25240 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
25250 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
25260 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
25270 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
25280 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
25290 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
252a0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
252b0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
252c0 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
252d0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
252e0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
252f0 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
25300 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
25310 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
25320 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
25330 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
25340 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
25350 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
25360 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
25370 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
25380 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
25390 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
253a0 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
253b0 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
253c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
253d0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
253e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
253f0 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
25400 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
25410 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
25420 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
25430 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
25440 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
25450 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
25460 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
25470 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
25480 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
25490 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
254a0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
254b0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
254c0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
254d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
254e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
254f0 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74  ost recent sqlit
25500 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
25510 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
25520 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
25530 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64  ection] D failed
25540 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
25550 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e  e3_errcode(D) in
25560 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
25570 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
25580 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
25590 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
255a0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a   code] for that.
255b0 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20  ** API call..** 
255c0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
255d0 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20  nt API call was 
255e0 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74  successful,.** t
255f0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
25600 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
25610 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
25620 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68  ndefined..** ^Th
25630 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
25640 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
25650 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
25660 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
25670 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
25680 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
25690 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
256a0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
256b0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
256c0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
256d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
256e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
256f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
25700 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
25710 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
25720 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
25730 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
25740 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
25750 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
25760 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
25770 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
25780 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
25790 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
257a0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
257b0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
257c0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
257d0 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
257e0 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
257f0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
25800 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
25810 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
25820 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
25830 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
25840 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
25850 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
25860 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
25870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25880 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
25890 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
258a0 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
258b0 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
258c0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
258d0 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
258e0 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
258f0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
25900 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
25910 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
25920 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
25930 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
25940 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
25950 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
25960 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
25970 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
25980 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
25990 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
259a0 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
259b0 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
259c0 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
259d0 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
259e0 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
259f0 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
25a00 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
25a10 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
25a20 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
25a30 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
25a40 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
25a50 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
25a60 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
25a70 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
25a80 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
25a90 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
25aa0 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
25ab0 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
25ac0 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
25ad0 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
25ae0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25af0 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
25b00 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
25b10 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
25b20 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
25b30 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
25b40 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
25b50 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
25b60 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
25b70 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
25b80 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
25b90 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
25ba0 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
25bb0 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
25bc0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
25bd0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
25be0 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
25bf0 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
25c00 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
25c10 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
25c20 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
25c30 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
25c40 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
25c50 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
25c60 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
25c70 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
25c80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
25c90 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
25ca0 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
25cb0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
25cc0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
25cd0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25ce0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
25cf0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
25d00 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
25d10 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
25d20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25d30 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
25d40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25d50 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
25d60 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
25d70 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
25d80 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
25d90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25da0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
25db0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
25dc0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
25dd0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
25de0 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61  ement that.** ha
25df0 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20  s been compiled 
25e00 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d  into binary form
25e10 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f   and is ready to
25e20 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a   be evaluated..*
25e30 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61  *.** Think of ea
25e40 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
25e50 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63   as a separate c
25e60 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e  omputer program.
25e70 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61    The.** origina
25e80 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f  l SQL text is so
25e90 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72  urce code.  A pr
25ea0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25eb0 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74   object .** is t
25ec0 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65  he compiled obje
25ed0 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51  ct code.  All SQ
25ee0 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  L must be conver
25ef0 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72  ted into a.** pr
25f00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25f10 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
25f20 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  e run..**.** The
25f30 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61   life-cycle of a
25f40 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25f50 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c  ent object usual
25f60 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69  ly goes like thi
25f70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
25f80 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
25f90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25fa0 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  ent object using
25fb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25fc0 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e  e_v2()]..** <li>
25fd0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
25fe0 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69  [parameters] usi
25ff0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
26000 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
26010 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
26020 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
26030 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
26040 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
26050 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
26060 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
26070 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26080 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
26090 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
260a0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
260b0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
260c0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
260d0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
260e0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
260f0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
26100 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
26110 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65  ** </ol>.*/.type
26120 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
26130 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
26140 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
26150 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
26160 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44  Limits.** METHOD
26170 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
26180 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
26190 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
261a0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
261b0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
261c0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
261d0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
261e0 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
261f0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
26200 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
26210 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26220 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
26230 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
26240 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
26250 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
26260 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
26270 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
26280 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
26290 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
262a0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
262b0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
262c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
262d0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
262e0 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
262f0 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
26300 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
26310 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
26320 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
26330 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
26340 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
26350 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
26360 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
26370 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
26380 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
26390 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
263a0 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
263b0 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
263c0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
263d0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
263e0 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
263f0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
26400 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
26410 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
26420 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
26430 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
26440 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
26450 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
26460 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
26470 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
26480 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
26490 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
264a0 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
264b0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
264c0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
264d0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
264e0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
264f0 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
26500 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
26510 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
26520 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
26530 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
26540 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
26550 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
26560 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
26570 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
26580 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
26590 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
265a0 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
265b0 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
265c0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
265d0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
265e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
265f0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
26600 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
26610 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
26620 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
26630 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
26640 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
26650 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
26660 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
26670 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
26680 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
26690 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
266a0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
266b0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
266c0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
266d0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
266e0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
266f0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
26700 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
26710 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
26720 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
26730 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
26740 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
26750 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
26760 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
26770 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
26780 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
26790 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
267a0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
267b0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
267c0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
267d0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
267e0 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
267f0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
26800 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
26810 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
26820 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
26830 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
26840 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
26850 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
26860 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
26870 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
26880 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
26890 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
268a0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
268b0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
268c0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
268d0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
268e0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
268f0 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
26900 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
26910 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
26920 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
26930 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
26940 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
26950 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
26960 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
26970 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
26980 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
26990 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
269a0 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
269b0 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
269c0 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
269d0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
269e0 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
269f0 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
26a00 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
26a10 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
26a20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
26a30 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
26a40 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
26a50 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
26a60 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
26a70 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
26a80 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
26a90 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
26aa0 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
26ab0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26ac0 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
26ad0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
26ae0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
26af0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
26b00 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
26b10 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
26b20 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
26b30 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
26b40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
26b50 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
26b60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
26b70 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
26b80 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
26b90 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
26ba0 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
26bb0 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
26bc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26bd0 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
26be0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
26bf0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
26c00 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26c10 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
26c20 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
26c30 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
26c40 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
26c50 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
26c60 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
26c70 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
26c80 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
26c90 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
26ca0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
26cb0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26cc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
26cd0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
26ce0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
26cf0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
26d00 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
26d10 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
26d20 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
26d30 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
26d40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26d50 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
26d60 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
26d70 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
26d80 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
26d90 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26da0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
26db0 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
26dc0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
26dd0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
26de0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
26df0 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
26e00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
26e10 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
26e20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26e30 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
26e40 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
26e50 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
26e60 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
26e70 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
26e80 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
26e90 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
26ea0 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
26eb0 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
26ec0 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
26ed0 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
26ee0 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
26ef0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
26f00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
26f10 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
26f20 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
26f30 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
26f40 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26f50 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
26f60 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
26f70 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
26f80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26f90 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
26fa0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26fb0 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
26fc0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26fd0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
26fe0 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
26ff0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
27000 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
27010 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
27020 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
27030 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
27040 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
27050 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
27060 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
27070 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
27080 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
27090 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
270a0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
270b0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
270c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
270d0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
270e0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
270f0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
27100 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
27110 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
27120 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
27130 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
27140 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
27150 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
27160 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
27170 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
27180 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
27190 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
271a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
271b0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
271c0 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
271d0 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
271e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
271f0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
27200 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
27210 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
27220 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
27230 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
27240 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
27250 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
27260 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
27270 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27280 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
27290 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
272a0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
272b0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
272c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
272d0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
272e0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
272f0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
27300 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
27310 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
27320 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
27330 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
27340 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
27350 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
27360 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
27370 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
27380 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
27390 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
273a0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
273b0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
273c0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
273d0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
273e0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
273f0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
27400 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27410 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
27420 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
27430 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27440 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
27450 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
27460 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27470 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
27480 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
27490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
274a0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
274b0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
274c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
274d0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
274e0 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
274f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27500 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
27510 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
27520 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
27530 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
27540 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
27550 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
27560 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
27570 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
27580 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
27590 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
275a0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
275b0 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
275c0 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
275d0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
275e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
275f0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
27600 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
27610 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
27620 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
27630 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
27640 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
27650 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
27660 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
27670 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
27680 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
27690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
276a0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
276b0 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
276c0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
276d0 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
276e0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
276f0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
27700 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
27710 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
27720 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
27730 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
27740 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
27750 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
27760 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
27770 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
27780 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
27790 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
277a0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
277b0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
277c0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
277d0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
277e0 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
277f0 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
27800 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
27810 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
27820 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
27830 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
27840 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
27850 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
27860 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
27870 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
27880 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
27890 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
278a0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
278b0 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
278c0 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
278d0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
278e0 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
278f0 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
27900 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
27910 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
27920 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
27930 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
27940 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
27950 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
27960 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
27970 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
27980 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
27990 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
279a0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
279b0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
279c0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
279d0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
279e0 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
279f0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
27a00 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
27a10 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
27a20 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
27a30 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
27a40 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
27a50 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
27a60 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
27a70 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
27a80 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
27a90 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
27aa0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
27ab0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27ac0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
27ad0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
27ae0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
27af0 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
27b00 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
27b10 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
27b20 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
27b30 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
27b40 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
27b50 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
27b60 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
27b70 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
27b80 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
27b90 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
27ba0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
27bb0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
27bc0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
27bd0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
27be0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
27bf0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
27c00 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
27c10 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
27c20 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
27c30 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
27c40 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
27c50 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
27c60 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
27c70 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
27c80 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
27c90 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
27ca0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
27cb0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
27cc0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
27cd0 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
27ce0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27cf0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
27d00 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
27d10 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
27d20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
27d30 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
27d40 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
27d50 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
27d60 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
27d70 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
27d80 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
27d90 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
27da0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
27db0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27dc0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
27dd0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
27de0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
27df0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
27e00 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
27e10 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
27e20 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
27e30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
27e40 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
27e50 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
27e60 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
27e70 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
27e80 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
27e90 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
27ea0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
27eb0 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
27ec0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
27ed0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
27ee0 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
27ef0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
27f00 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
27f10 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
27f20 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
27f30 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
27f40 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
27f50 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
27f60 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
27f70 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
27f80 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
27f90 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
27fa0 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
27fb0 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
27fc0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
27fd0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
27fe0 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
27ff0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
28000 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
28010 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
28020 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
28030 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
28040 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
28050 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
28060 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
28070 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
28080 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
28090 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
280a0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
280b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
280c0 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
280d0 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
280e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
280f0 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
28100 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
28110 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
28120 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
28130 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
28140 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
28150 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
28160 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
28170 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
28180 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
28190 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
281a0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
281b0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
281c0 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
281d0 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
281e0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
281f0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
28200 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
28210 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
28220 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
28230 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
28240 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
28250 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
28260 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
28270 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
28280 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
28290 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
282a0 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
282b0 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
282c0 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
282d0 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
282e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
282f0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
28300 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
28310 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
28320 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
28330 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
28340 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
28350 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
28360 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
28370 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
28380 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
28390 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
283a0 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
283b0 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
283c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
283d0 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
283e0 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
283f0 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
28400 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
28410 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
28420 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
28430 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
28440 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
28450 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
28460 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
28470 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
28480 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
28490 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
284a0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
284b0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
284c0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
284d0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
284e0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
284f0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28500 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
28510 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
28520 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28530 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28540 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
28550 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
28560 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
28570 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
28580 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
28590 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
285a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
285b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
285c0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
285d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
285e0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
285f0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
28600 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
28610 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
28620 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
28630 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
28640 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
28650 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
28660 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
28670 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
28680 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
28690 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
286a0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
286b0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
286c0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
286d0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
286e0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
286f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
28700 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
28710 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
28720 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
28730 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
28740 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
28750 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
28760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
28770 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
28780 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
28790 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
287a0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
287b0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
287c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
287d0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
287e0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
287f0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
28800 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
28810 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
28820 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
28830 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28840 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28850 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28860 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
28870 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
28880 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
28890 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
288a0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
288b0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
288c0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
288d0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
288e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
288f0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28900 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28910 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
28920 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28930 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28940 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28950 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
28960 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28970 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
28980 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
28990 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
289a0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
289b0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
289c0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
289d0 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
289e0 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
289f0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
28a00 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
28a10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
28a20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
28a30 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
28a40 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
28a50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
28a60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
28a70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
28a80 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
28a90 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
28aa0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
28ab0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28ac0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
28ad0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
28ae0 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
28af0 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
28b00 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
28b10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
28b20 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
28b30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28b40 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
28b50 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
28b60 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
28b70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
28b80 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
28b90 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
28ba0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
28bb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
28bc0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
28bd0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28be0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
28bf0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
28c00 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
28c10 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
28c20 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
28c30 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
28c40 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
28c50 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
28c60 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
28c70 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
28c80 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
28c90 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
28ca0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
28cb0 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
28cc0 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
28cd0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
28ce0 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
28cf0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
28d00 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
28d10 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
28d20 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
28d30 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
28d40 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
28d50 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
28d60 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
28d70 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
28d80 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
28d90 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
28da0 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
28db0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28dc0 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
28dd0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
28de0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
28df0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
28e00 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
28e10 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
28e20 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
28e30 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
28e40 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
28e50 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
28e60 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
28e70 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
28e80 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
28e90 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
28ea0 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
28eb0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
28ec0 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
28ed0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
28ee0 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
28ef0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
28f00 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
28f10 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
28f20 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
28f30 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
28f40 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
28f50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28f60 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
28f70 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
28f80 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
28f90 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
28fa0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
28fb0 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
28fc0 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
28fd0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
28fe0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
28ff0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
29000 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
29010 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71   disk..*/.int sq
29020 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
29030 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
29040 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
29050 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
29060 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
29070 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
29080 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d   Been Reset.** M
29090 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
290a0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
290b0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
290c0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
290d0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
290e0 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
290f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29100 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
29110 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
29120 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
29130 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
29140 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65  ] but has neithe
29150 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  r run to complet
29160 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a  ion (returned.**
29170 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66   [SQLITE_DONE] f
29180 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rom [sqlite3_ste
29190 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65  p(S)]) nor.** be
291a0 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
291b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
291c0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
291d0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
291e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
291f0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
29200 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
29210 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
29220 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
29230 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
29240 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
29250 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29260 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
29270 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
29280 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
29290 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
292a0 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
292b0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
292c0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
292d0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
292e0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
292f0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
29300 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29310 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
29320 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
29330 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
29340 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
29350 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
29360 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
29370 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
29380 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
29390 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
293a0 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
293b0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
293c0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
293d0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
293e0 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  pen..*/.int sqli
293f0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
29400 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
29410 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
29420 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
29430 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
29440 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
29450 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29460 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
29470 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
29480 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
29490 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
294a0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
294b0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
294c0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
294d0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
294e0 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
294f0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
29500 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
29510 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
29520 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
29530 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
29540 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
29550 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
29560 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
29570 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
29580 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
29590 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
295a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
295b0 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
295c0 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
295d0 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
295e0 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
295f0 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
29600 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29610 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
29620 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
29630 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
29640 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
29650 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29660 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
29670 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
29680 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
29690 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
296a0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
296b0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
296c0 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
296d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
296e0 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ue.  The.** [sql
296f0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29  ite3_value_dup()
29700 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ] interface can 
29710 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74  be used to const
29720 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70  ruct a new .** p
29730 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29740 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75  _value from an u
29750 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
29760 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
29770 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
29780 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
29790 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
297a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
297b0 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
297c0 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
297d0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
297e0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
297f0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
29800 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
29810 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
29820 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
29830 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
29840 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
29850 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
29860 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
29870 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
29880 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
29890 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
298a0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
298b0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
298c0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
298d0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
298e0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
298f0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
29900 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
29910 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
29920 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
29930 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
29940 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
29950 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
29960 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
29970 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
29980 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
29990 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
299a0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
299b0 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
299c0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
299d0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
299e0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
299f0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
29a00 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
29a10 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
29a20 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
29a30 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
29a40 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
29a50 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
29a60 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
29a70 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
29a80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29a90 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
29aa0 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
29ab0 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
29ac0 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
29ad0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
29ae0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29af0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
29b00 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
29b10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
29b20 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
29b30 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
29b40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
29b50 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
29b60 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
29b70 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29b80 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
29b90 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
29ba0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
29bb0 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
29bc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
29bd0 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
29be0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
29bf0 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
29c00 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
29c10 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
29c20 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
29c30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29c40 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
29c50 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
29c60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
29c70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29c80 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
29c90 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
29ca0 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
29cb0 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
29cc0 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
29cd0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
29ce0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
29cf0 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
29d00 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
29d10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
29d20 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
29d30 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
29d40 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
29d50 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
29d60 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
29d70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29d80 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
29d90 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
29da0 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
29db0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
29dc0 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
29dd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
29de0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
29df0 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
29e00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29e10 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
29e20 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
29e30 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
29e40 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
29e50 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
29e60 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
29e70 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
29e80 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
29e90 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
29ea0 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
29eb0 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
29ec0 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
29ed0 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
29ee0 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
29ef0 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
29f00 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
29f10 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
29f20 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
29f30 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
29f40 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
29f50 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
29f60 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
29f70 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
29f80 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  g}.** METHOD: sq
29f90 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
29fa0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
29fb0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
29fc0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
29fd0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
29fe0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
29ff0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
2a000 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
2a010 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
2a020 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
2a030 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
2a040 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
2a050 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
2a060 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
2a070 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
2a080 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
2a090 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
2a0a0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
2a0b0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
2a0c0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
2a0d0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
2a0e0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
2a0f0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
2a100 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
2a110 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
2a120 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
2a130 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
2a140 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
2a150 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
2a160 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
2a170 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
2a180 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2a190 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2a1a0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
2a1b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2a1c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2a1d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2a1e0 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
2a1f0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
2a200 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
2a210 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
2a220 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
2a230 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a240 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
2a250 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
2a260 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2a270 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2a280 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
2a290 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
2a2a0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
2a2b0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
2a2c0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
2a2d0 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
2a2e0 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
2a2f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
2a300 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
2a310 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
2a320 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
2a330 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
2a340 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
2a350 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
2a360 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
2a370 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
2a380 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
2a390 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
2a3a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
2a3b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2a3c0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
2a3d0 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
2a3e0 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
2a3f0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
2a400 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
2a410 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
2a420 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
2a430 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
2a440 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
2a450 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
2a460 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2a470 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
2a480 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
2a490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2a4a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2a4b0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
2a4c0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
2a4d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
2a4e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2a4f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a500 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2a510 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
2a520 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
2a530 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
2a540 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
2a550 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2a560 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
2a570 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
2a580 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
2a590 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
2a5a0 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
2a5b0 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
2a5c0 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
2a5d0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
2a5e0 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
2a5f0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2a600 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
2a610 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
2a620 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
2a630 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2a640 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
2a650 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
2a660 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2a670 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
2a680 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2a690 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2a6a0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2a6b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a6c0 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
2a6d0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
2a6e0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
2a6f0 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
2a700 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
2a710 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
2a720 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2a730 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
2a740 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2a750 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2a760 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
2a770 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
2a780 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2a790 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
2a7a0 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
2a7b0 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
2a7c0 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
2a7d0 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
2a7e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a7f0 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65  xt16() or sqlite
2a800 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2a810 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72  then.** that par
2a820 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
2a830 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
2a840 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
2a850 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
2a860 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
2a870 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
2a880 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
2a890 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
2a8a0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
2a8b0 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
2a8c0 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
2a8d0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
2a8e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2a8f0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
2a900 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
2a910 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
2a920 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
2a930 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
2a940 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
2a950 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
2a960 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
2a970 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
2a980 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2a990 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2a9a0 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67   BLOB and string
2a9b0 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61   binding interfa
2a9c0 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74  ces.** is a dest
2a9d0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
2a9e0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2a9f0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
2aa00 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
2aa10 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2aa20 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
2aa30 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
2aa40 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2aa50 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
2aa60 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
2aa70 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66  ll to bind API f
2aa80 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ails..** ^If the
2aa90 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2aaa0 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
2aab0 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
2aac0 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
2aad0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2aae0 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
2aaf0 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
2ab00 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
2ab10 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
2ab20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
2ab30 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2ab40 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
2ab50 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
2ab60 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
2ab70 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
2ab80 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
2ab90 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
2aba0 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
2abb0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
2abc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2abd0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
2abe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2abf0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2ac00 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2ac10 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  4() must be one 
2ac20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  of.** [SQLITE_UT
2ac30 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2ac40 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
2ac50 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
2ac60 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f  E_UTF16LE].** to
2ac70 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63   specify the enc
2ac80 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78  oding of the tex
2ac90 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  t in the third p
2aca0 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a  arameter.  If.**
2acb0 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d   the sixth argum
2acc0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2acd0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20  ind_text64() is 
2ace0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
2acf0 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  * allowed values
2ad00 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72   shown above, or
2ad10 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63   if the text enc
2ad20 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
2ad30 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65  nt.** from the e
2ad40 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
2ad50 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70  d by the sixth p
2ad60 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
2ad70 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
2ad80 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2ad90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ada0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
2adb0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
2adc0 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
2add0 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
2ade0 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
2adf0 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
2ae00 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
2ae10 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
2ae20 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
2ae30 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
2ae40 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
2ae50 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
2ae60 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
2ae70 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
2ae80 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
2ae90 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
2aea0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
2aeb0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
2aec0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
2aed0 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
2aee0 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
2aef0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
2af00 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
2af10 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
2af20 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
2af30 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
2af40 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
2af50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2af60 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
2af70 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
2af80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2af90 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2afa0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
2afb0 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
2afc0 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
2afd0 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
2afe0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
2aff0 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
2b000 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
2b010 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
2b020 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
2b030 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
2b040 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
2b050 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
2b060 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
2b070 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
2b080 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b090 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
2b0a0 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
2b0b0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2b0c0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2b0d0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
2b0e0 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
2b0f0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
2b100 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2b110 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
2b120 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
2b130 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
2b140 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
2b150 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b160 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
2b170 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2b180 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
2b190 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
2b1a0 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
2b1b0 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2b1c0 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
2b1d0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2b1e0 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66  d if the size of
2b1f0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2b200 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d  B.** exceeds lim
2b210 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b  its imposed by [
2b220 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2b230 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2b240 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c  GTH]) or.** [SQL
2b250 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e  ITE_MAX_LENGTH].
2b260 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
2b270 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
2b280 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2b290 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
2b2a0 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
2b2b0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
2b2c0 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
2b2d0 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
2b2e0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b2f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b300 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
2b310 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2b320 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2b330 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2b340 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2b350 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2b360 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2b370 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b380 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2b390 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
2b3a0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2b3b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34  ite3_bind_blob64
2b3c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b3d0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2b3e0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2b3f0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2b400 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2b410 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2b420 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
2b430 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2b440 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
2b450 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b460 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2b470 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
2b480 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b490 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2b4a0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2b4b0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
2b4c0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2b4d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b4e0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2b4f0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2b500 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
2b510 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
2b520 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2b530 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2b540 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2b550 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2b560 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2b570 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2b580 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2b590 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2b5a0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2b5b0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2b5c0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2b5d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2b5e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
2b5f0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2b600 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69  oding);.int sqli
2b610 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
2b620 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b630 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
2b640 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2b650 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2b660 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2b670 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
2b680 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b690 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69  _zeroblob64(sqli
2b6a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b6b0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
2b6c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b6d0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
2b6e0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45  Parameters.** ME
2b6f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2b700 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  mt.**.** ^This r
2b710 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2b720 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
2b730 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
2b740 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
2b750 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b760 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
2b770 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
2b780 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
2b790 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
2b7a0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
2b7b0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
2b7c0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
2b7d0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
2b7e0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
2b7f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2b800 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
2b810 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
2b820 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
2b830 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2b840 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
2b850 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
2b860 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
2b870 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
2b880 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
2b890 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
2b8a0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
2b8b0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
2b8c0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
2b8d0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
2b8e0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2b8f0 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
2b900 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
2b910 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
2b920 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
2b930 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b940 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2b950 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2b960 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b970 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2b980 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2b990 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b9a0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2b9b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b9c0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2b9d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2b9e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b9f0 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
2ba00 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54  Parameter.** MET
2ba10 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2ba20 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2ba30 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ba40 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
2ba50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2ba60 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
2ba70 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
2ba80 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
2ba90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2baa0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
2bab0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2bac0 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
2bad0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2bae0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
2baf0 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
2bb00 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
2bb10 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2bb20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2bb30 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
2bb40 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
2bb50 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
2bb60 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
2bb70 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
2bb80 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
2bb90 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
2bba0 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
2bbb0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2bbc0 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
2bbd0 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
2bbe0 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
2bbf0 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
2bc00 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
2bc10 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
2bc20 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
2bc30 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
2bc40 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2bc50 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
2bc60 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
2bc70 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
2bc80 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
2bc90 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
2bca0 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
2bcb0 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
2bcc0 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
2bcd0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2bce0 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
2bcf0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
2bd00 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
2bd10 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
2bd20 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
2bd30 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
2bd40 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
2bd50 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
2bd60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bd70 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2bd80 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2bd90 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2bda0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2bdb0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2bdc0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2bdd0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2bde0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2bdf0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2be00 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2be10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2be20 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2be30 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2be40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2be50 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2be60 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2be70 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Name.** METHOD: 
2be80 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2be90 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2bea0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2beb0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2bec0 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2bed0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2bee0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2bef0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2bf00 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2bf10 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2bf20 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2bf30 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2bf40 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2bf50 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2bf60 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2bf70 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2bf80 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2bf90 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2bfa0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2bfb0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2bfc0 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2bfd0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2bfe0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2bff0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2c000 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2c010 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2c020 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2c030 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2c040 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2c050 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2c060 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2c070 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2c080 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ame()]..*/.int s
2c090 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2c0a0 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
2c0b0 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
2c0c0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
2c0d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c0e0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
2c0f0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
2c100 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
2c110 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c120 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  mt.**.** ^Contra
2c130 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2c140 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2c150 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2c160 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2c170 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2c180 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2c190 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2c1a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2c1b0 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2c1c0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2c1d0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2c1e0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
2c1f0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2c200 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2c210 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2c220 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2c230 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2c240 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2c250 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c260 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
2c270 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2c280 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2c290 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
2c2a0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
2c2b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c2c0 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
2c2d0 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
2c2e0 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
2c2f0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
2c300 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
2c310 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2c320 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2c330 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2c340 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2c350 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
2c360 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2c370 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2c380 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2c390 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
2c3a0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
2c3b0 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2c3c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2c3d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2c3e0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2c3f0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2c400 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2c410 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2c420 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2c430 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2c440 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2c450 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2c460 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c470 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2c480 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2c490 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2c4a0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2c4b0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2c4c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2c4d0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2c4e0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2c4f0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2c500 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2c510 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c520 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2c530 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2c540 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2c550 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2c560 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2c570 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2c580 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2c590 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2c5a0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2c5b0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2c5c0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2c5d0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2c5e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2c5f0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2c600 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2c610 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c620 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2c630 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2c640 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2c650 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2c660 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2c670 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2c680 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2c690 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2c6a0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2c6b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c6c0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2c6d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2c6e0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2c6f0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2c700 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2c710 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2c720 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2c730 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2c740 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2c750 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2c760 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2c770 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2c780 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2c790 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2c7a0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2c7b0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2c7c0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2c7d0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2c7e0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2c7f0 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2c800 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2c810 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2c820 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2c830 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2c840 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2c850 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2c860 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2c870 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2c880 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2c890 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2c8a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2c8b0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2c8c0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
2c8d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c8e0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2c8f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2c900 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c910 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2c920 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2c930 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
2c940 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2c950 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2c960 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
2c970 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
2c980 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
2c990 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
2c9a0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
2c9b0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
2c9c0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
2c9d0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
2c9e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2c9f0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
2ca00 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2ca10 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
2ca20 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
2ca30 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
2ca40 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
2ca50 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2ca60 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
2ca70 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
2ca80 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
2ca90 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
2caa0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2cab0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
2cac0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
2cad0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2cae0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
2caf0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2cb00 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
2cb10 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
2cb20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cb30 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
2cb40 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2cb50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2cb60 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2cb70 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2cb80 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2cb90 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2cba0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2cbb0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2cbc0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2cbd0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
2cbe0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
2cbf0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
2cc00 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
2cc10 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
2cc20 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
2cc30 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
2cc40 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
2cc50 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
2cc60 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
2cc70 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
2cc80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2cc90 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2cca0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
2ccb0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2ccc0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
2ccd0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2cce0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2ccf0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
2cd00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
2cd10 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
2cd20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
2cd30 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
2cd40 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2cd50 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
2cd60 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
2cd70 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
2cd80 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
2cd90 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
2cda0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2cdb0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
2cdc0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
2cdd0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
2cde0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
2cdf0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
2ce00 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
2ce10 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
2ce20 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
2ce30 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
2ce40 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
2ce50 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2ce60 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
2ce70 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
2ce80 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
2ce90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
2cea0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2ceb0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
2cec0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
2ced0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
2cee0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
2cef0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
2cf00 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
2cf10 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
2cf20 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
2cf30 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
2cf40 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
2cf50 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
2cf60 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
2cf70 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
2cf80 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
2cf90 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
2cfa0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2cfb0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2cfc0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2cfd0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2cfe0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2cff0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2d000 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
2d010 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2d020 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2d030 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2d040 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
2d050 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
2d060 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
2d070 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
2d080 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2d090 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
2d0a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2d0b0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2d0c0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2d0d0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
2d0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2d0f0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
2d100 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
2d110 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
2d120 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
2d130 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
2d140 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
2d150 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2d160 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2d170 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2d180 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2d190 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d1a0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
2d1b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2d1c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2d1d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2d1e0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
2d1f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2d200 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2d210 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2d220 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2d230 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2d240 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2d250 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2d260 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2d270 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
2d280 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2d290 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
2d2a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2d2b0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2d2c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2d2d0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
2d2e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2d2f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d300 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
2d310 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
2d320 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
2d330 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d340 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
2d350 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
2d360 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d370 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
2d380 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
2d390 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2d3a0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
2d3b0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
2d3c0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
2d3d0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
2d3e0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
2d3f0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
2d400 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2d410 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
2d420 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
2d430 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
2d440 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
2d450 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
2d460 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2d470 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
2d480 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2d490 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
2d4a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2d4b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
2d4c0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2d4d0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
2d4e0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
2d4f0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2d500 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
2d510 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
2d520 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
2d530 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
2d540 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
2d550 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
2d560 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2d570 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
2d580 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
2d590 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
2d5a0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
2d5b0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
2d5c0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
2d5d0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
2d5e0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
2d5f0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
2d600 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
2d610 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
2d620 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
2d630 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2d640 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
2d650 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
2d660 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
2d670 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
2d680 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
2d690 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
2d6a0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
2d6b0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
2d6c0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
2d6d0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
2d6e0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
2d6f0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
2d700 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
2d710 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
2d720 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
2d730 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
2d740 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
2d750 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
2d760 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
2d770 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
2d780 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
2d790 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
2d7a0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2d7b0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
2d7c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2d7d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d7e0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2d7f0 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2d800 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2d810 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2d820 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2d830 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
2d840 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d850 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
2d860 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
2d870 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
2d880 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
2d890 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d8a0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2d8b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2d8c0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
2d8d0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2d8e0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
2d8f0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
2d900 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d910 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
2d920 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
2d930 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2d940 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
2d950 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2d960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
2d970 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
2d980 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
2d990 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
2d9a0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
2d9b0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
2d9c0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
2d9d0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
2d9e0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
2d9f0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
2da00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2da10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2da20 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
2da30 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
2da40 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
2da50 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2da60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2da70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
2da80 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
2da90 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2daa0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
2dab0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
2dac0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
2dad0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2dae0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
2daf0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
2db00 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
2db10 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2db20 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2db30 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
2db40 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
2db50 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
2db60 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
2db70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
2db80 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2db90 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
2dba0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
2dbb0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
2dbc0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
2dbd0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
2dbe0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
2dbf0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
2dc00 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
2dc10 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
2dc20 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
2dc30 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
2dc40 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
2dc50 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
2dc60 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
2dc70 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
2dc80 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
2dc90 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
2dca0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
2dcb0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
2dcc0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2dcd0 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
2dce0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
2dcf0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
2dd00 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
2dd10 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
2dd20 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
2dd30 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
2dd40 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
2dd50 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
2dd60 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2dd70 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
2dd80 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
2dd90 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
2dda0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
2ddb0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
2ddc0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
2ddd0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
2dde0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2ddf0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2de00 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
2de10 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2de20 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
2de30 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2de40 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
2de50 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
2de60 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
2de70 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2de80 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
2de90 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2dea0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
2deb0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
2dec0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
2ded0 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
2dee0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
2def0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
2df00 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
2df10 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
2df20 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
2df30 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
2df40 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
2df50 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2df60 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
2df70 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
2df80 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
2df90 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
2dfa0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
2dfb0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
2dfc0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
2dfd0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
2dfe0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
2dff0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
2e000 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
2e010 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2e020 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2e030 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
2e040 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
2e050 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
2e060 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
2e070 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
2e080 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
2e090 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2e0a0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
2e0b0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2e0c0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
2e0d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
2e0e0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
2e0f0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
2e100 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
2e110 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
2e120 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
2e130 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2e140 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
2e150 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2e160 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
2e170 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2e180 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
2e190 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2e1a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
2e1b0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
2e1c0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
2e1d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
2e1e0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
2e1f0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
2e200 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
2e210 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
2e220 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
2e230 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2e240 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2e250 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
2e260 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
2e270 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
2e280 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
2e290 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
2e2a0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
2e2b0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
2e2c0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
2e2d0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
2e2e0 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
2e2f0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2e300 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
2e310 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
2e320 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
2e330 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
2e340 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
2e350 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
2e360 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2e370 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
2e380 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
2e390 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2e3a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
2e3b0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
2e3c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
2e3d0 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
2e3e0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
2e3f0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
2e400 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
2e410 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
2e420 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2e430 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
2e440 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2e450 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
2e460 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
2e470 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
2e480 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
2e490 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
2e4a0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
2e4b0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
2e4c0 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
2e4d0 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
2e4e0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
2e4f0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2e500 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
2e510 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
2e520 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
2e530 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
2e540 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
2e550 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
2e560 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
2e570 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
2e580 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
2e590 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
2e5a0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
2e5b0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
2e5c0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
2e5d0 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
2e5e0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
2e5f0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
2e600 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2e610 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
2e620 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
2e630 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
2e640 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
2e650 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
2e660 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
2e670 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2e680 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
2e690 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
2e6a0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
2e6b0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
2e6c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2e6d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
2e6e0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
2e6f0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
2e700 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
2e710 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
2e720 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
2e730 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2e740 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2e750 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
2e760 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
2e770 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2e780 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
2e790 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
2e7a0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
2e7b0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
2e7c0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
2e7d0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
2e7e0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
2e7f0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
2e800 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
2e810 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
2e820 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
2e830 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
2e840 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2e850 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2e860 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2e870 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
2e880 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
2e890 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e8a0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2e8b0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
2e8c0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
2e8d0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
2e8e0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2e8f0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
2e900 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
2e910 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2e920 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
2e930 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2e940 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
2e950 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
2e960 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
2e970 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e980 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
2e990 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
2e9a0 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   set.** METHOD: 
2e9b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e9c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e9d0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
2e9e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2e9f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2ea00 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
2ea10 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2ea20 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2ea30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ea40 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
2ea50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ea60 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
2ea70 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
2ea80 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
2ea90 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
2eaa0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2eab0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
2eac0 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
2ead0 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
2eae0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2eaf0 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
2eb00 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2eb10 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2eb20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
2eb30 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
2eb40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2eb50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2eb60 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2eb70 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2eb80 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
2eb90 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2eba0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2ebb0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
2ebc0 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
2ebd0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
2ebe0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
2ebf0 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
2ec00 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
2ec10 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2ec20 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
2ec30 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
2ec40 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
2ec50 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
2ec60 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
2ec70 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
2ec80 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
2ec90 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
2eca0 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
2ecb0 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
2ecc0 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
2ecd0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
2ece0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
2ecf0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
2ed00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
2ed10 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
2ed20 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2ed30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ed40 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
2ed50 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
2ed60 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
2ed70 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
2ed80 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
2ed90 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
2eda0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
2edb0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2edc0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
2edd0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2ede0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
2edf0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2ee00 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
2ee10 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
2ee20 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
2ee30 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
2ee40 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2ee50 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
2ee60 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
2ee70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
2ee80 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
2ee90 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
2eea0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
2eeb0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
2eec0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
2eed0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
2eee0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
2eef0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
2ef00 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
2ef10 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
2ef20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2ef30 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
2ef40 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
2ef50 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
2ef60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ef70 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
2ef80 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
2ef90 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2efa0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
2efb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
2efc0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
2efd0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2efe0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2eff0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2f000 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2f010 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2f020 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2f030 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2f040 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2f050 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2f060 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2f070 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2f080 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
2f090 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f0a0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2f0b0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
2f0c0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
2f0d0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
2f0e0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
2f0f0 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
2f100 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
2f110 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2f120 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2f130 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2f140 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f150 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2f160 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2f170 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2f180 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2f190 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2f1a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2f1b0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2f1c0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2f1d0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2f1e0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2f1f0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2f200 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2f210 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2f220 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
2f230 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2f240 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2f250 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2f260 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
2f270 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2f280 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
2f290 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
2f2a0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2f2b0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2f2c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
2f2d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
2f2e0 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
2f2f0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
2f300 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
2f310 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
2f320 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2f330 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
2f340 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
2f350 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
2f360 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2f370 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
2f380 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
2f390 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f3a0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
2f3b0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
2f3c0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2f3d0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
2f3e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2f3f0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
2f400 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
2f410 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
2f420 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2f430 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
2f440 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f450 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2f460 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2f470 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2f480 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2f490 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
2f4a0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
2f4b0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
2f4c0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2f4d0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
2f4e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2f4f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2f500 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2f510 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
2f520 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
2f530 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2f540 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
2f550 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2f560 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
2f570 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2f580 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2f590 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2f5a0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
2f5b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2f5c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2f5d0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
2f5e0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
2f5f0 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
2f600 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
2f610 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
2f620 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
2f630 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2f640 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
2f650 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2f660 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
2f670 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
2f680 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
2f690 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
2f6a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2f6b0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
2f6c0 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
2f6d0 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
2f6e0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
2f6f0 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
2f700 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
2f710 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
2f720 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
2f730 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
2f740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2f750 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
2f760 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
2f770 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2f780 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
2f790 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
2f7a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2f7b0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
2f7c0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
2f7d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2f7e0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2f7f0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2f800 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2f810 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2f820 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2f830 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2f840 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2f850 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2f860 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f870 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
2f880 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2f890 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f8a0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2f8b0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
2f8c0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2f8d0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2f8e0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2f8f0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2f900 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2f910 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f920 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
2f930 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2f940 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2f950 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2f960 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
2f970 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2f980 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2f990 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2f9a0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2f9b0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2f9c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f9d0 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
2f9e0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
2f9f0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2fa00 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
2fa10 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2fa20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fa30 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
2fa40 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2fa50 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2fa60 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2fa70 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2fa80 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2fa90 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
2faa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fab0 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
2fac0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2fad0 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
2fae0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2faf0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2fb00 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2fb10 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2fb20 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2fb30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2fb40 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2fb50 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2fb60 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2fb70 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
2fb80 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
2fb90 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2fba0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2fbb0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2fbc0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2fbd0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2fbe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fbf0 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
2fc00 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
2fc10 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2fc20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2fc30 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
2fc40 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2fc50 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
2fc60 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2fc70 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
2fc80 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
2fc90 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
2fca0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
2fcb0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2fcc0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2fcd0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2fce0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2fcf0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
2fd00 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
2fd10 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
2fd20 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
2fd30 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2fd40 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
2fd50 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2fd60 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2fd70 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2fd80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2fd90 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2fda0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2fdb0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
2fdc0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
2fdd0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
2fde0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
2fdf0 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
2fe00 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
2fe10 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2fe20 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e  r..**.** <b>Warn
2fe30 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62  ing:</b> ^The ob
2fe40 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2fe50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2fe60 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2fe70 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2fe80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2fe90 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c  bject.  In a mul
2fea0 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72  tithreaded envir
2feb0 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e  onment,.** an un
2fec0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2fed0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
2fee0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2fef0 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b  safely with.** [
2ff00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2ff10 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2ff20 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2ff30 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
2ff40 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2ff50 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2ff60 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2ff70 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2ff80 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
2ff90 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
2ffa0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
2ffb0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
2ffc0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2ffd0 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
2ffe0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2fff0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
30000 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
30010 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f  ()], the behavio
30020 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  r is not threads
30030 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  afe..**.** These
30040 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
30050 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
30060 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
30070 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
30080 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
30090 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
300a0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
300b0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
300c0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
300d0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
300e0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
300f0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
30100 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
30110 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
30120 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
30130 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
30140 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
30150 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
30160 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
30170 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
30180 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
30190 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
301a0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
301b0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
301c0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
301d0 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
301e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
301f0 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
30200 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
30210 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
30220 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
30230 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
30240 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
30250 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
30260 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
30270 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
30280 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
30290 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
302a0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
302b0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
302c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
302d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
302e0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
302f0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
30300 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
30310 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
30320 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
30330 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
30340 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
30350 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
30360 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
30370 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
30380 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
30390 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
303a0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
303b0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
303c0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
303d0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
303e0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
303f0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
30400 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
30410 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
30420 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
30430 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
30440 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
30450 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74  o BLOB.** <tr><t
30460 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
30470 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
30480 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
30490 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  R.** <tr><td>  T
304a0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
304b0 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
304c0 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
304d0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
304e0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
304f0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
30500 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
30510 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30520 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
30530 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
30540 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
30550 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
30560 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
30570 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
30580 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
30590 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
305a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
305b0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
305c0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
305d0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  uote>)^.**.** No
305e0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
305f0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
30600 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
30610 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
30620 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
30630 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30640 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
30650 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
30660 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
30670 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
30680 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
30690 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
306a0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
306b0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
306c0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
306d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
306e0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
306f0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
30700 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
30710 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
30720 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
30730 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
30740 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30750 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
30760 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
30770 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
30780 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
30790 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
307a0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
307b0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
307c0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
307d0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
307e0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
307f0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
30800 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
30810 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
30820 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
30830 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
30840 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
30850 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
30860 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
30870 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
30880 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30890 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
308a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
308b0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
308c0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
308d0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
308e0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
308f0 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
30900 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
30910 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
30920 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
30930 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
30940 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
30950 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
30960 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
30970 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
30980 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
30990 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
309a0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
309b0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
309c0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
309d0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
309e0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
309f0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
30a00 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
30a10 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
30a20 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
30a30 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
30a40 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
30a50 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
30a60 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
30a70 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
30a80 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f  ** The safest po
30a90 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
30aa0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
30ab0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
30ac0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
30ad0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
30ae0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
30af0 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
30b00 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
30b10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
30b20 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
30b30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
30b40 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
30b50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30b60 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
30b70 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
30b80 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
30b90 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
30ba0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
30bb0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
30bc0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
30bd0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
30be0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
30bf0 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
30c00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30c10 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
30c20 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
30c30 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
30c40 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
30c50 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
30c60 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
30c70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30c80 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
30c90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30ca0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
30cb0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
30cc0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
30cd0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
30ce0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30cf0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
30d00 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
30d10 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
30d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30d30 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
30d40 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
30d50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30d60 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
30d70 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
30d80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
30d90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
30da0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
30db0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
30dc0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
30dd0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
30de0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
30df0 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
30e00 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
30e10 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
30e20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
30e30 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
30e40 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
30e50 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
30e60 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
30e70 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
30e80 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
30e90 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e   Do <em>not</em>
30ea0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
30eb0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
30ec0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
30ed0 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
30ee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30ef0 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
30f00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
30f10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
30f20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
30f30 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
30f40 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
30f50 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
30f60 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
30f70 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
30f80 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
30f90 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
30fa0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
30fb0 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
30fc0 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
30fd0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
30fe0 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
30ff0 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
31000 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
31010 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
31020 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
31030 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
31040 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
31050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
31060 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
31070 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
31080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31090 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
310a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
310b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
310c0 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
310d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
310e0 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
310f0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
31100 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31110 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
31120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
31130 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
31140 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
31150 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
31160 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
31170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31180 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
31190 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
311a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
311b0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
311c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
311d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
311e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
311f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31200 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
31210 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
31220 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31230 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
31240 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
31250 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
31260 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31270 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
31280 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
31290 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
312a0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
312b0 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
312c0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
312d0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
312e0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
312f0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
31300 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
31310 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
31320 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
31330 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
31340 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
31350 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
31360 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
31370 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
31380 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
31390 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
313a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
313b0 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
313c0 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
313d0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
313e0 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
313f0 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
31400 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
31410 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
31420 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
31430 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
31440 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
31450 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
31460 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
31470 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
31480 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
31490 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
314a0 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
314b0 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
314c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
314d0 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
314e0 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
314f0 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
31500 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
31510 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
31520 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
31530 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
31540 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31550 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
31560 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
31570 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
31580 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
31590 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
315a0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
315b0 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
315c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
315d0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
315e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
315f0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
31600 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
31610 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31620 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
31630 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
31640 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
31650 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
31660 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
31670 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
31680 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
31690 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
316a0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
316b0 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
316c0 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
316d0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
316e0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
316f0 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
31700 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
31710 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
31720 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
31730 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
31740 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
31750 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
31760 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
31770 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
31780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
31790 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
317a0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
317b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
317c0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
317d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
317e0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
317f0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
31800 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31810 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
31820 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
31830 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
31840 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
31850 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
31860 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
31870 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
31880 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
31890 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
318a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
318b0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
318c0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
318d0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
318e0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
318f0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
31900 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
31910 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
31920 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
31930 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
31940 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
31950 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31960 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
31970 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
31980 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
31990 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
319a0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
319b0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
319c0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
319d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
319e0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
319f0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
31a00 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
31a10 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
31a20 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
31a30 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
31a40 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
31a50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
31a60 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
31a70 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
31a80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
31a90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
31aa0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
31ab0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
31ac0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
31ad0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
31ae0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
31af0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
31b00 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
31b10 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
31b20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
31b30 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
31b40 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
31b50 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
31b60 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
31b70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
31b80 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
31b90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31ba0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
31bb0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
31bc0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
31bd0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
31be0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
31bf0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
31c00 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
31c10 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
31c20 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
31c30 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
31c40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31c50 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
31c60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
31c70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31c80 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
31c90 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
31ca0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
31cb0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
31cc0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
31cd0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
31ce0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
31cf0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
31d00 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
31d10 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
31d20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
31d30 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
31d40 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
31d50 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
31d60 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
31d70 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
31d80 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
31d90 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
31da0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
31db0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
31dc0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
31dd0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
31de0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
31df0 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
31e00 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
31e10 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
31e20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
31e30 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
31e40 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
31e50 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
31e60 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31e70 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
31e80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31e90 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
31ea0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
31eb0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
31ec0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
31ed0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
31ee0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
31ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
31f00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31f10 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
31f20 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
31f30 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
31f40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
31f50 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
31f60 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
31f70 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
31f80 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
31f90 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
31fa0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
31fb0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
31fc0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
31fd0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
31fe0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
31ff0 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
32000 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
32010 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
32020 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
32030 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
32040 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
32050 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
32060 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
32070 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
32080 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
32090 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
320a0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
320b0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
320c0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
320d0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
320e0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
320f0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
32100 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
32110 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
32120 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
32130 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
32140 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
32150 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
32160 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
32170 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
32180 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
32190 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
321a0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
321b0 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
321c0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
321d0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
321e0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
321f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
32200 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
32210 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
32220 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
32230 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
32240 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
32250 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
32260 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
32270 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
32280 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
32290 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
322a0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
322b0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
322c0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
322d0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
322e0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
322f0 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
32300 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
32310 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
32320 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
32330 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
32340 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
32350 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
32360 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
32370 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
32380 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
32390 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
323a0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
323b0 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
323c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
323d0 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
323e0 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
323f0 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
32400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32410 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
32420 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
32430 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
32440 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
32450 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
32460 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
32470 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
32480 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
32490 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
324a0 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
324b0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
324c0 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
324d0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
324e0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
324f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
32500 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
32510 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
32520 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
32530 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
32540 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
32550 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
32560 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
32570 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
32580 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
32590 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
325a0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
325b0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
325c0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
325d0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
325e0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
325f0 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
32600 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
32610 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
32620 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
32630 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
32640 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
32650 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
32660 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
32670 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
32680 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
32690 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
326a0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
326b0 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
326c0 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
326d0 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
326e0 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
326f0 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
32700 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
32710 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
32720 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
32730 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
32740 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
32750 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
32760 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
32770 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
32780 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
32790 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
327a0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
327b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
327c0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
327d0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
327e0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
327f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
32800 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
32810 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
32820 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
32830 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
32840 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
32850 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
32860 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
32870 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
32880 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
32890 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
328a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
328b0 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
328c0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
328d0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
328e0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
328f0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
32900 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
32910 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
32920 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
32930 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
32940 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
32950 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
32960 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
32970 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32980 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
32990 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
329a0 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
329b0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
329c0 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
329d0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
329e0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
329f0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
32a00 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
32a10 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
32a20 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
32a30 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
32a40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
32a50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32a60 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
32a70 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
32a80 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
32a90 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
32aa0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
32ab0 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
32ac0 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
32ad0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
32ae0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
32af0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
32b00 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
32b10 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
32b20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
32b30 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
32b40 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
32b50 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
32b60 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
32b70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32b80 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
32b90 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
32ba0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
32bb0 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
32bc0 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
32bd0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
32be0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
32bf0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
32c00 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
32c10 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
32c20 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
32c30 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
32c40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
32c50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32c60 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
32c70 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
32c80 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
32c90 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
32ca0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
32cb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
32cc0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
32cd0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
32ce0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
32cf0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
32d00 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
32d10 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
32d20 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
32d30 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
32d40 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32d50 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
32d60 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
32d70 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
32d80 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
32d90 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
32da0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
32db0 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
32dc0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
32dd0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
32de0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
32df0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
32e00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
32e10 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
32e20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
32e30 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
32e40 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
32e50 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
32e60 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
32e70 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
32e80 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
32e90 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
32ea0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
32eb0 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
32ec0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
32ed0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
32ee0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
32ef0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
32f00 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
32f10 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
32f20 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
32f30 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
32f40 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
32f50 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
32f60 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
32f70 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
32f80 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
32f90 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
32fa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32fb0 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
32fc0 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
32fd0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32fe0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
32ff0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
33000 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
33010 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
33020 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
33030 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
33040 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33050 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
33060 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
33070 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
33080 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
33090 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
330a0 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
330b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
330c0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
330d0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
330e0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
330f0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
33100 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
33110 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
33120 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
33130 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
33140 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
33150 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
33160 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
33170 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
33180 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
33190 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
331a0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
331b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
331c0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
331d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
331e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
331f0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
33200 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
33210 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
33220 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
33230 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
33240 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
33250 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
33260 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
33270 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
33280 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
33290 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
332a0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
332b0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
332c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
332d0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
332e0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
332f0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
33300 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
33310 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
33320 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
33330 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
33340 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33350 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
33360 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
33370 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
33380 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
33390 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
333a0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
333b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
333c0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
333d0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
333e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
333f0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
33400 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
33410 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
33420 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
33430 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
33440 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
33450 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
33460 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
33470 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
33480 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f            1    /
33490 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33  * IMP: R-37514-3
334a0 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20  5566 */.#define 
334b0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
334c0 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d        2    /* IM
334d0 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37  P: R-03371-37637
334e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
334f0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
33500 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    3    /* IMP: R
33510 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a  -51971-34154 */.
33520 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
33530 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
33540 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
33550 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
33560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
33570 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
33580 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
33590 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
335a0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
335b0 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
335c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
335d0 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
335e0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
335f0 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
33600 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
33610 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
33620 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
33630 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
33640 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
33650 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
33660 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
33670 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
33680 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
33690 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
336a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
336b0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
336c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
336d0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
336e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
336f0 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
33700 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
33710 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
33720 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
33730 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
33740 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
33750 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
33760 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
33770 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
33780 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
33790 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
337a0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
337b0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
337c0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
337d0 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
337e0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
337f0 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
33800 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
33810 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61  ons.  To encoura
33820 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74  ge programmers t
33830 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65  o avoid.** these
33840 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77   functions, we w
33850 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20  ill not explain 
33860 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
33870 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
33880 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
33890 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
338a0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
338b0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
338c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
338d0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
338e0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
338f0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
33900 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
33910 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
33920 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
33930 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
33940 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
33950 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
33960 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
33970 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
33980 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
33990 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
339a0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
339b0 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
339c0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
339d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
339e0 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
339f0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
33a00 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
33a10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33a20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
33a30 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
33a40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33a50 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61  Obtaining SQL Va
33a60 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
33a70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
33a80 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
33a90 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
33aa0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
33ab0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
33ac0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
33ad0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
33ae0 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
33af0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
33b00 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
33b10 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
33b20 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a  gregate.  .**.**
33b30 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
33b40 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
33b50 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
33b60 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
33b70 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
33b80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33b90 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
33ba0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33bb0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
33bc0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
33bd0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
33be0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
33bf0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
33c00 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
33c10 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
33c20 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
33c30 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
33c40 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
33c50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
33c60 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
33c70 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
33c80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
33c90 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
33ca0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
33cb0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
33cc0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
33cd0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
33ce0 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
33cf0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33d00 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
33d10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
33d20 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
33d30 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
33d40 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
33d50 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
33d60 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
33d70 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
33d80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
33d90 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
33da0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
33db0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
33dc0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
33dd0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
33de0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
33df0 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
33e00 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
33e10 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
33e20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
33e30 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
33e40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
33e50 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
33e60 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
33e70 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
33e80 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
33e90 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
33ea0 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
33eb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
33ec0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
33ed0 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
33ee0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
33ef0 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
33f00 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
33f10 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
33f20 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
33f30 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
33f40 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
33f50 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
33f60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
33f70 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
33f80 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
33f90 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
33fa0 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
33fb0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
33fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
33fd0 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
33fe0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
33ff0 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
34000 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
34010 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
34020 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
34030 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
34040 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
34050 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
34060 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
34070 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
34080 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
34090 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
340a0 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
340b0 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
340c0 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
340d0 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
340e0 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
340f0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
34100 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
34110 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
34120 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
34130 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
34140 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
34150 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
34160 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
34170 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
34180 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
34190 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
341a0 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
341b0 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
341c0 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
341d0 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
341e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
341f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
34200 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
34210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
34220 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
34230 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
34240 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
34250 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
34260 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
34270 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
34280 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
34290 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
342a0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
342b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
342c0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
342d0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
342e0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
342f0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
34300 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
34310 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
34320 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
34330 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
34340 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
34350 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
34360 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
34370 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
34380 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
34390 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
343a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
343b0 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
343c0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
343d0 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
343e0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
343f0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
34400 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
34410 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34420 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
34430 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
34440 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
34450 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
34460 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
34470 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
34480 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
34490 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
344a0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
344b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
344c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
344d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
344e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
344f0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
34500 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34510 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
34520 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
34530 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
34540 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
34550 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
34560 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
34570 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
34580 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
34590 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79  inding The Subty
345a0 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73  pe Of SQL Values
345b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
345c0 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
345d0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
345e0 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e  e_subtype(V) fun
345f0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
34600 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a  e subtype for.**
34610 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   an [application
34620 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
34630 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20  ction] argument 
34640 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a  V.  The subtype.
34650 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63  ** information c
34660 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61  an be used to pa
34670 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f  ss a limited amo
34680 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66  unt of context f
34690 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66  rom.** one SQL f
346a0 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68  unction to anoth
346b0 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71  er.  Use the [sq
346c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
346d0 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  type()].** routi
346e0 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75  ne to set the su
346f0 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65  btype for the re
34700 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
34710 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
34720 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  *.** SQLite make
34730 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74  s no use of subt
34740 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20  ype itself.  It 
34750 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68  merely passes th
34760 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f  e subtype.** fro
34770 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  m the result of 
34780 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  one [application
34790 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
347a0 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a  ction] into the.
347b0 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74  ** input of anot
347c0 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64  her..*/.unsigned
347d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
347e0 75 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74  ue_subtype(sqlit
347f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
34800 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70  ** CAPI3REF: Cop
34810 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56  y And Free SQL V
34820 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
34830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
34840 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34850 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
34860 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
34870 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
34880 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
34890 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74  object D and ret
348a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
348b0 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54  o that copy.  ^T
348c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
348d0 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  e] returned.** i
348e0 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73  s a [protected s
348f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34900 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65  ject even if the
34910 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a   input is not..*
34920 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
34930 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65  alue_dup(V) inte
34940 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55  rface returns NU
34950 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20  LL if V is NULL 
34960 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72  or if a.** memor
34970 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
34980 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ls..**.** ^The s
34990 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
349a0 65 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66  e(V) interface f
349b0 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  rees an [sqlite3
349c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
349d0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
349e0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
349f0 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d  te3_value_dup()]
34a00 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55  .  ^If V is a NU
34a10 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  LL pointer.** th
34a20 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  en sqlite3_value
34a30 5f 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61  _free(V) is a ha
34a40 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
34a50 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
34a60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
34a70 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  p(const sqlite3_
34a80 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
34a90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
34aa0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34ab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34ac0 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
34ad0 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
34ae0 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  text.** METHOD: 
34af0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
34b00 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
34b10 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
34b20 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
34b30 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
34b40 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
34b50 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
34b60 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
34b70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
34b80 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
34b90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34ba0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
34bb0 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
34bc0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
34bd0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
34be0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
34bf0 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
34c00 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
34c10 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
34c20 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
34c30 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
34c40 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
34c50 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
34c60 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
34c70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34c80 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
34c90 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
34ca0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
34cb0 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
34cc0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
34cd0 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
34ce0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
34cf0 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
34d00 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
34d10 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
34d20 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
34d30 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
34d40 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
34d50 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
34d60 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
34d70 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
34d80 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
34d90 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
34da0 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
34db0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
34dc0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
34dd0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
34de0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
34df0 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
34e00 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
34e10 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
34e20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
34e30 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34e40 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
34e50 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
34e60 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
34e70 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
34e80 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
34e90 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
34ea0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
34eb0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
34ec0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
34ed0 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
34ee0 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
34ef0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
34f00 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
34f10 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
34f20 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
34f30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
34f40 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
34f50 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
34f60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34f70 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
34f80 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
34f90 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
34fa0 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
34fb0 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
34fc0 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
34fd0 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
34fe0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
34ff0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35000 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
35010 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
35020 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
35030 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
35040 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
35050 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
35060 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69    Within the xFi
35070 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  nal callback, it
35080 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f   is customary to
35090 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63   set.** N=0 in c
350a0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
350b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
350c0 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e  t(C,N) so that n
350d0 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20  o .** pointless 
350e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
350f0 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20  ns occur..**.** 
35100 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
35110 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
35120 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
35130 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
35140 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
35150 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
35160 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
35170 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
35180 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
35190 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
351a0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
351b0 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
351c0 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
351d0 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
351e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
351f0 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
35200 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
35210 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
35220 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
35230 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
35240 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
35250 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
35260 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
35270 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
35280 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
35290 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
352a0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
352b0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
352c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
352d0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
352e0 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
352f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35300 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
35310 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
35320 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
35330 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ntext.**.** ^The
35340 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
35350 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
35360 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
35370 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
35380 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
35390 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
353a0 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
353b0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
353c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
353d0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
353e0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
353f0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
35400 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
35410 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
35420 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
35430 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
35440 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
35450 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
35460 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
35470 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
35480 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
35490 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
354a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
354b0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
354c0 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
354d0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
354e0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
354f0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
35500 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
35510 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
35520 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
35530 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  text.**.** ^The 
35540 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
35550 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
35560 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
35570 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
35580 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
35590 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
355a0 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
355b0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
355c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
355d0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
355e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
355f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35600 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
35610 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
35620 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
35630 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
35640 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73  d function..*/.s
35650 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
35660 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
35670 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35680 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
35690 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
356a0 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
356b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
356c0 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54  _context.**.** T
356d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d  hese functions m
356e0 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e  ay be used by (n
356f0 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51  on-aggregate) SQ
35700 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
35710 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
35720 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
35730 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
35740 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
35750 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
35760 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
35770 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
35780 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
35790 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
357a0 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
357b0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
357c0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
357d0 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
357e0 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61  eserved.  An exa
357f0 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65  mple.** of where
35800 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75   this might be u
35810 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65  seful is in a re
35820 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
35830 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e   matching.** fun
35840 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
35850 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
35860 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
35870 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f  ssion can be sto
35880 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
35890 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
358a0 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73  th the pattern s
358b0 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e  tring.  .** Then
358c0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
358d0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72  pattern string r
358e0 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c  emains the same,
358f0 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  .** the compiled
35900 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
35910 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
35920 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
35930 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
35940 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
35950 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
35960 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
35970 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
35980 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35990 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
359a0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
359b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
359c0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
359d0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
359e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
359f0 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
35a00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35a10 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72  nction. ^If ther
35a20 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61  e is no metadata
35a30 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
35a40 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ith the function
35a50 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20   argument, this 
35a60 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
35a70 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ata() interface.
35a80 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ** returns a NUL
35a90 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
35aa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
35ab0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
35ac0 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  X) interface sav
35ad0 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61  es P as metadata
35ae0 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
35af0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
35b00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35b10 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
35b20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63  ^Subsequent.** c
35b30 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
35b40 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29  get_auxdata(C,N)
35b50 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74   return P from t
35b60 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
35b70 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
35b80 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63  xdata(C,N,P,X) c
35b90 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64  all if the metad
35ba0 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c  ata is still val
35bb0 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66  id or.** NULL if
35bc0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61   the metadata ha
35bd0 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64  s been discarded
35be0 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68  ..** ^After each
35bf0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
35c00 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
35c10 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73  ,P,X) where X is
35c20 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51   not NULL,.** SQ
35c30 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
35c40 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
35c50 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20  function X with 
35c60 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63  parameter P exac
35c70 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65  tly.** once, whe
35c80 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  n the metadata i
35c90 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  s discarded..** 
35ca0 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
35cb0 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65  o discard the me
35cc0 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69  tadata at any ti
35cd0 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c  me, including: <
35ce0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e  ul>.** <li> when
35cf0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
35d00 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
35d10 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f  meter changes, o
35d20 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b  r.** <li> when [
35d30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
35d40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
35d50 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
35d60 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  ed for the.**   
35d70 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74     SQL statement
35d80 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
35d90 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  n sqlite3_set_au
35da0 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b  xdata() is invok
35db0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20  ed again on the 
35dc0 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  same parameter, 
35dd0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e  or.** <li> durin
35de0 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  g the original s
35df0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35e00 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61  ta() call when a
35e10 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20   memory .**     
35e20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
35e30 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29  r occurs. </ul>)
35e40 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65  ^.**.** Note the
35e50 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20   last bullet in 
35e60 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65  particular.  The
35e70 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e   destructor X in
35e80 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74   .** sqlite3_set
35e90 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
35ea0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
35eb0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  d immediately, b
35ec0 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c  efore the.** sql
35ed0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35ee0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65  () interface eve
35ef0 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63  n returns.  Henc
35f00 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
35f10 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c  xdata().** shoul
35f20 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72  d be called near
35f30 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
35f40 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
35f50 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a  ntation and the.
35f60 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ** function impl
35f70 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
35f80 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75  d not make any u
35f90 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a  se of P after.**
35fa0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35fb0 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20  data() has been 
35fc0 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  called..**.** ^(
35fd0 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
35fe0 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
35ff0 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
36000 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
36010 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
36020 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f  ters that are co
36030 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74  mpile-time const
36040 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ants, including 
36050 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
36060 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
36070 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f  s] and expressio
36080 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d  ns composed from
36090 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a   the same.)^.**.
360a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
360b0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
360c0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
360d0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
360e0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
360f0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
36100 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
36110 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
36120 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36130 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
36140 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
36150 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36160 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
36170 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
36180 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
36190 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
361a0 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
361b0 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
361c0 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
361d0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
361e0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
361f0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
36200 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
36210 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
36220 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
36230 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
36240 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
36250 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
36260 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
36270 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
36280 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
36290 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
362a0 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
362b0 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
362c0 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
362d0 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
362e0 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
362f0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
36300 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
36310 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
36320 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
36330 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
36340 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
36350 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
36360 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
36370 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
36380 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
36390 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
363a0 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
363b0 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
363c0 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
363d0 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
363e0 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a  C++ compilers..*
363f0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
36400 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
36410 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
36420 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
36430 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
36440 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
36450 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
36460 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
36470 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
36480 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
36490 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
364a0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
364b0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
364c0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54   Function.** MET
364d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
364e0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  text.**.** These
364f0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
36500 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
36510 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
36520 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
36530 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
36540 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
36550 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
36560 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
36570 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
36580 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
36590 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
365a0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
365b0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
365c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
365d0 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
365e0 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
365f0 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
36600 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
36610 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
36620 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
36630 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
36640 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
36650 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
36660 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
36670 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
36680 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
36690 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
366a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
366b0 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
366c0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
366d0 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
366e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
366f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
36700 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
36710 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
36720 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
36730 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
36740 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
36750 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
36760 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
36770 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
36780 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36790 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
367a0 6c 6f 62 28 43 2c 4e 29 20 61 6e 64 20 73 71 6c  lob(C,N) and sql
367b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
367c0 62 6c 6f 62 36 34 28 43 2c 4e 29 0a 2a 2a 20 69  blob64(C,N).** i
367d0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
367e0 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
367f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36800 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
36810 62 65 0a 2a 2a 20 61 20 42 4c 4f 42 20 63 6f 6e  be.** a BLOB con
36820 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
36830 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
36840 65 73 20 69 6e 20 73 69 7a 65 2e 0a 2a 2a 0a 2a  es in size..**.*
36850 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36860 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
36870 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36880 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
36890 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
368a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
368b0 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
368c0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
368d0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
368e0 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
368f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36900 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36910 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
36920 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
36930 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
36940 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
36950 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
36960 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
36970 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  tion..** ^SQLite
36980 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
36990 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
369a0 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
369b0 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
369c0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
369d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
369e0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
369f0 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
36a00 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e  rror message.  ^
36a10 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
36a20 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
36a30 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
36a40 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
36a50 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
36a60 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69  -8. ^SQLite.** i
36a70 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
36a80 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
36a90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36aa0 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
36ab0 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
36ac0 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74  rder.  ^If the t
36ad0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
36ae0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
36af0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
36b00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36b10 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
36b20 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
36b30 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
36b40 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
36b50 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
36b60 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
36b70 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
36b80 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
36b90 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
36ba0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
36bb0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
36bc0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
36bd0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
36be0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
36bf0 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
36c00 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
36c10 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
36c20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
36c30 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
36c40 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  e..** ^The sqlit
36c50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36c60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
36c70 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
36c80 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
36c90 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
36ca0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
36cb0 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
36cc0 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
36cd0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
36ce0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
36cf0 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
36d00 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
36d10 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
36d20 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
36d30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
36d40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
36d50 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
36d60 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
36d70 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
36d80 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
36d90 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
36da0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
36db0 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c  n.  ^By default,
36dc0 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
36dd0 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
36de0 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65  OR.  ^A subseque
36df0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
36e00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36e10 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
36e20 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
36e30 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
36e40 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
36e50 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _ERROR..**.** ^T
36e60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36e70 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29  t_error_toobig()
36e80 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
36e90 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
36ea0 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
36eb0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
36ec0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
36ed0 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
36ee0 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
36ef0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36f00 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29  lt_error_nomem()
36f10 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
36f20 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
36f30 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
36f40 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
36f50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
36f60 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
36f70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36f80 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
36f90 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
36fa0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
36fb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36fc0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36fd0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
36fe0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
36ff0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
37000 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
37010 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ent..** ^The sql
37020 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
37030 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
37040 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
37050 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
37060 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37070 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37080 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
37090 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
370a0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
370b0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
370c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
370d0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
370e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
370f0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
37100 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
37110 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37120 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
37130 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
37140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37150 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
37160 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
37170 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37180 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
37190 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
371a0 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
371b0 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
371c0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
371d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
371e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
371f0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
37200 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
37210 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
37220 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
37230 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
37240 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
37250 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
37260 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
37270 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
37280 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
37290 73 75 6c 74 5f 74 65 78 74 36 34 28 29 20 69 6e  sult_text64() in
372a0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
372b0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
372c0 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69   an.** applicati
372d0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
372e0 69 6f 6e 20 74 6f 20 62 65 20 61 20 74 65 78 74  ion to be a text
372f0 20 73 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e   string in an en
37300 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66  coding.** specif
37310 69 65 64 20 62 79 20 74 68 65 20 66 69 66 74 68  ied by the fifth
37320 20 28 61 6e 64 20 6c 61 73 74 29 20 70 61 72 61   (and last) para
37330 6d 65 74 65 72 2c 20 77 68 69 63 68 20 6d 75 73  meter, which mus
37340 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b  t be one.** of [
37350 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
37360 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
37370 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
37380 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
37390 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  LE]..** ^SQLite 
373a0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
373b0 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
373c0 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
373d0 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
373e0 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
373f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
37400 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
37410 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
37420 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
37430 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37440 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
37450 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
37460 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
37470 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
37480 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
37490 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
374a0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
374b0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
374c0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
374d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
374e0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
374f0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
37500 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
37510 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
37520 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
37530 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
37540 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
37550 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
37560 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
37570 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37580 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
37590 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33  esult.  If the 3
375a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
375b0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
375c0 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65  en it.** must be
375d0 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
375e0 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67   into the string
375f0 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
37600 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a  erminator would.
37610 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65  ** appear if the
37620 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55   string where NU
37630 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  L terminated.  I
37640 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
37650 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ters occur.** in
37660 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61   the string at a
37670 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61   byte offset tha
37680 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74  t is less than t
37690 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
376a0 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  3rd.** parameter
376b0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
376c0 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c  ting string will
376d0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
376e0 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a  d NULs and the.*
376f0 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  * result of expr
37700 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e  essions operatin
37710 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74  g on strings wit
37720 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
37730 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
37740 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
37750 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
37760 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37770 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
37780 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
37790 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
377a0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
377b0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
377c0 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
377d0 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
377e0 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
377f0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
37800 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
37810 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
37820 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
37830 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
37840 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
37850 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
37860 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
37870 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
37880 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
37890 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
378a0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
378b0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
378c0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
378d0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
378e0 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
378f0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
37900 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
37910 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
37920 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
37930 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
37940 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
37950 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
37960 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
37970 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
37980 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
37990 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
379a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
379b0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
379c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
379d0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
379e0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
379f0 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
37a00 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
37a10 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
37a20 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
37a30 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
37a40 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
37a50 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
37a60 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
37a70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37a80 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
37a90 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
37aa0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
37ab0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37ac0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37ad0 74 6f 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  to be a copy of 
37ae0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
37af0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
37b00 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
37b10 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
37b20 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
37b30 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
37b40 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
37b50 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
37b60 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
37b70 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
37b80 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
37b90 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
37ba0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
37bb0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
37bc0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
37bd0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
37be0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
37bf0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
37c00 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
37c10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
37c20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
37c30 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
37c40 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
37c50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
37c60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
37c70 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
37c80 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
37c90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
37ca0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
37cb0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
37cc0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
37cd0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
37ce0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
37cf0 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
37d00 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
37d10 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
37d20 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
37d30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37d40 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
37d50 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
37d60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
37d70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
37d80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
37d90 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
37da0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
37db0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37dc0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
37dd0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
37de0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
37df0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34 28 73  _result_blob64(s
37e00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37e10 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20 20 20  const void*,.   
37e20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37e30 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
37e40 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29 28 76  uint64,void(*)(v
37e50 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
37e60 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
37e70 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
37e80 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
37e90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37ea0 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
37eb0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37ec0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
37ed0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37ee0 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
37ef0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
37f00 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
37f10 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37f20 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
37f30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
37f40 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
37f50 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
37f60 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
37f70 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
37f80 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
37f90 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
37fa0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
37fb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37fc0 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
37fd0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
37fe0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37ff0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
38000 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
38010 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
38020 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
38030 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38040 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
38050 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
38060 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
38070 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
38080 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
38090 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
380a0 65 73 75 6c 74 5f 74 65 78 74 36 34 28 73 71 6c  esult_text64(sql
380b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
380c0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
380d0 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
380e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
380f0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
38100 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
38110 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 76  har encoding);.v
38120 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
38130 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
38140 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
38150 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
38160 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
38170 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
38180 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
38190 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
381a0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
381b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
381c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
381d0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
381e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
381f0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
38200 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
38210 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
38220 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
38230 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
38240 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
38250 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
38260 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
38270 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
38280 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33   n);.int sqlite3
38290 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
382a0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
382b0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  xt*, sqlite3_uin
382c0 74 36 34 20 6e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  t64 n);.../*.** 
382d0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
382e0 67 20 54 68 65 20 53 75 62 74 79 70 65 20 4f 66  g The Subtype Of
382f0 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
38300 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
38310 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
38320 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
38330 73 75 6c 74 5f 73 75 62 74 79 70 65 28 43 2c 54  sult_subtype(C,T
38340 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
38350 73 20 74 68 65 20 73 75 62 74 79 70 65 20 6f 66  s the subtype of
38360 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 20 66  .** the result f
38370 72 6f 6d 20 74 68 65 20 5b 61 70 70 6c 69 63 61  rom the [applica
38380 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
38390 20 66 75 6e 63 74 69 6f 6e 5d 20 77 69 74 68 20   function] with 
383a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
383b0 74 65 78 74 5d 20 43 20 74 6f 20 62 65 20 74 68  text] C to be th
383c0 65 20 76 61 6c 75 65 20 54 2e 20 20 4f 6e 6c 79  e value T.  Only
383d0 20 74 68 65 20 6c 6f 77 65 72 20 38 20 62 69 74   the lower 8 bit
383e0 73 20 0a 2a 2a 20 6f 66 20 74 68 65 20 73 75 62  s .** of the sub
383f0 74 79 70 65 20 54 20 61 72 65 20 70 72 65 73 65  type T are prese
38400 72 76 65 64 20 69 6e 20 63 75 72 72 65 6e 74 20  rved in current 
38410 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
38420 74 65 3b 0a 2a 2a 20 68 69 67 68 65 72 20 6f 72  te;.** higher or
38430 64 65 72 20 62 69 74 73 20 61 72 65 20 64 69 73  der bits are dis
38440 63 61 72 64 65 64 2e 0a 2a 2a 20 54 68 65 20 6e  carded..** The n
38450 75 6d 62 65 72 20 6f 66 20 73 75 62 74 79 70 65  umber of subtype
38460 20 62 79 74 65 73 20 70 72 65 73 65 72 76 65 64   bytes preserved
38470 20 62 79 20 53 51 4c 69 74 65 20 6d 69 67 68 74   by SQLite might
38480 20 69 6e 63 72 65 61 73 65 0a 2a 2a 20 69 6e 20   increase.** in 
38490 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
384a0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f  of SQLite..*/.vo
384b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
384c0 74 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65  t_subtype(sqlite
384d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 75 6e 73 69 67  3_context*,unsig
384e0 6e 65 64 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ned int);../*.**
384f0 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
38500 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
38510 53 65 71 75 65 6e 63 65 73 0a 2a 2a 20 4d 45 54  Sequences.** MET
38520 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
38530 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
38540 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
38550 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
38560 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
38570 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
38580 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
38590 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
385a0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
385b0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
385c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
385d0 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
385e0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
385f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38600 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
38610 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
38620 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
38630 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
38640 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
38650 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
38660 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
38670 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
38680 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
38690 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
386a0 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
386b0 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
386c0 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
386d0 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
386e0 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
386f0 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
38700 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
38710 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
38720 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
38730 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
38740 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
38750 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
38760 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
38770 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
38780 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
38790 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
387a0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
387b0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
387c0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
387d0 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
387e0 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
387f0 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
38800 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
38810 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e