System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact bb73f067e50a0a2068b1f74768228ee9c13f86bf:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 33 2e 38 2e 31 31 2e 31 22 0a       "3.8.11.1".
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 33 30  ERSION_NUMBER 30
10d0: 30 38 30 31 31 0a 23 64 65 66 69 6e 65 20 53 51  08011.#define SQ
10e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
10f0: 20 20 20 20 22 32 30 31 35 2d 30 37 2d 32 39 20      "2015-07-29 
1100: 32 30 3a 30 30 3a 35 37 20 63 66 35 33 38 65 32  20:00:57 cf538e2
1110: 37 38 33 65 34 36 38 62 62 63 32 35 65 37 63 62  783e468bbc25e7cb
1120: 32 61 39 65 65 36 34 64 33 65 30 65 38 30 62 32  2a9ee64d3e0e80b2
1130: 66 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  f"../*.** CAPI3R
1140: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
1150: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
1160: 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  bers.** KEYWORDS
1170: 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  : sqlite3_versio
1180: 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  n, sqlite3_sourc
1190: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
11a0: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
11b0: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
11c0: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
11d0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
11e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
11f0: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
1200: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1210: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1220: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
1230: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
1240: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
1250: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1260: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
1270: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
1280: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
1290: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
12a0: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
12b0: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
12c0: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
12d0: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
12e0: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
12f0: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
1300: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
1310: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
1320: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
1330: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
1340: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
1350: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
1360: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
1370: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
1380: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
1390: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
13a0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
13b0: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
13c0: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
13d0: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
13e0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
13f0: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
1400: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
1410: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
1420: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1430: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
1440: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
1450: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1460: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1470: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1480: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
1490: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
14a0: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
14b0: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
14c0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14d0: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
14e0: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
14f0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
1500: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
1510: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
1520: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
1530: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1540: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
1550: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
1560: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
1570: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
1580: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
1590: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
15a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
15b0: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
15c0: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
15d0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
15e0: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
15f0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
1600: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
1610: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1620: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
1630: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
1640: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1650: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
1660: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
1670: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
1680: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
1690: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
16a0: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
16b0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
16c0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
16d0: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
16e0: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
16f0: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
1700: 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
1710: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
1720: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
1730: 73 69 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41  sion[];.SQLITE_A
1740: 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
1750: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1760: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1770: 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
1780: 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
1790: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
17a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
17b0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
17c0: 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
17d0: 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  ALL sqlite3_libv
17e0: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f  ersion_number(vo
17f0: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
1800: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1810: 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69  ibrary Compilati
1820: 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e  on Options Diagn
1830: 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ostics.**.** ^Th
1840: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1850: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66  eoption_used() f
1860: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1870: 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63  0 or 1 .** indic
1880: 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68  ating whether th
1890: 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69  e specified opti
18a0: 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61  on was defined a
18b0: 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69  t .** compile ti
18c0: 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  me.  ^The SQLITE
18d0: 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20  _ prefix may be 
18e0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
18f0: 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65   .** option name
1900: 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74   passed to sqlit
1910: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1920: 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a  _used().  .**.**
1930: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
1940: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1950: 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77  ) function allow
1960: 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f  s iterating.** o
1970: 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20  ver the list of 
1980: 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72  options that wer
1990: 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d  e defined at com
19a0: 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20  pile time by.** 
19b0: 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d  returning the N-
19c0: 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  th compile time 
19d0: 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20  option string.  
19e0: 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  ^If N is out of 
19f0: 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65  range,.** sqlite
1a00: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a10: 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20  get() returns a 
1a20: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1a30: 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20  The SQLITE_ .** 
1a40: 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65  prefix is omitte
1a50: 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e  d from any strin
1a60: 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a  gs returned by .
1a70: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1a80: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a  leoption_get()..
1a90: 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66  **.** ^Support f
1aa0: 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69  or the diagnosti
1ab0: 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69  c functions sqli
1ac0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1ad0: 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20  n_used().** and 
1ae0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1af0: 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20  ption_get() may 
1b00: 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70  be omitted by sp
1b10: 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a  ecifying the .**
1b20: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f   [SQLITE_OMIT_CO
1b30: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b40: 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d  S] option at com
1b50: 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  pile time..**.**
1b60: 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66   See also: SQL f
1b70: 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65  unctions [sqlite
1b80: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1b90: 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1ba0: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74  qlite_compileopt
1bb0: 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74  ion_get()] and t
1bc0: 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69  he [compile_opti
1bd0: 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a  ons pragma]..*/.
1be0: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
1bf0: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
1c00: 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41  N_DIAGS.SQLITE_A
1c10: 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
1c20: 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
1c30: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1c40: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70  (const char *zOp
1c50: 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41  tName);.SQLITE_A
1c60: 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
1c70: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1c80: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c90: 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a  ion_get(int N);.
1ca0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
1cb0: 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20  PI3REF: Test To 
1cc0: 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61  See If The Libra
1cd0: 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65  ry Is Threadsafe
1ce0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1cf0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
1d00: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1d10: 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e  s zero if and on
1d20: 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20  ly if.** SQLite 
1d30: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1d40: 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20  h mutexing code 
1d50: 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74  omitted due to t
1d60: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1d70: 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c  READSAFE] compil
1d80: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65  e-time option be
1d90: 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a  ing set to 0..**
1da0: 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62  .** SQLite can b
1db0: 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  e compiled with 
1dc0: 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78  or without mutex
1dd0: 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65  es.  When.** the
1de0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1df0: 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73  AFE] C preproces
1e00: 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f  sor macro is 1 o
1e10: 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20  r 2, mutexes.** 
1e20: 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20  are enabled and 
1e30: 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64  SQLite is thread
1e40: 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a  safe.  When the.
1e50: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
1e60: 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20  DSAFE] macro is 
1e70: 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  0, .** the mutex
1e80: 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20  es are omitted. 
1e90: 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74   Without the mut
1ea0: 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20  exes, it is not 
1eb0: 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53  safe.** to use S
1ec0: 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74  QLite concurrent
1ed0: 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61  ly from more tha
1ee0: 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a  n one thread..**
1ef0: 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74  .** Enabling mut
1f00: 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65  exes incurs a me
1f10: 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d  asurable perform
1f20: 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a  ance penalty..**
1f30: 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20   So if speed is 
1f40: 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74  of utmost import
1f50: 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73  ance, it makes s
1f60: 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a  ense to disable.
1f70: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20  ** the mutexes. 
1f80: 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d   But for maximum
1f90: 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73   safety, mutexes
1fa0: 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c   should be enabl
1fb0: 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  ed..** ^The defa
1fc0: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ult behavior is 
1fd0: 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62  for mutexes to b
1fe0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  e enabled..**.**
1ff0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2000: 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61  can be used by a
2010: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
2020: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20   make sure that 
2030: 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f  the.** version o
2040: 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74  f SQLite that it
2050: 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69   is linking agai
2060: 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  nst was compiled
2070: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73   with.** the des
2080: 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20  ired setting of 
2090: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
20a0: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a  ADSAFE] macro..*
20b0: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
20c0: 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ace only reports
20d0: 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d   on the compile-
20e0: 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69  time mutex setti
20f0: 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  ng.** of the [SQ
2100: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
2110: 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74   flag.  If SQLit
2120: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
2130: 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52  th.** SQLITE_THR
2140: 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20  EADSAFE=1 or =2 
2150: 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65  then mutexes are
2160: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
2170: 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62  ult but.** can b
2180: 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69  e fully or parti
2190: 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73  ally disabled us
21a0: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
21b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
21c0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72  .** with the ver
21d0: 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  bs [SQLITE_CONFI
21e0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c  G_SINGLETHREAD],
21f0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2200: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a  MULTITHREAD],.**
2210: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
2220: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20  IG_SERIALIZED]. 
2230: 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61   ^(The return va
2240: 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71  lue of the.** sq
2250: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2260: 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77  () function show
2270: 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69  s only the compi
2280: 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20  le-time setting 
2290: 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66  of.** thread saf
22a0: 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e  ety, not any run
22b0: 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f  -time changes to
22c0: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61   that setting ma
22d0: 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33  de by.** sqlite3
22e0: 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74  _config(). In ot
22f0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72  her words, the r
2300: 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
2310: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2320: 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68  afe().** is unch
2330: 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74  anged by calls t
2340: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
2350: 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ().)^.**.** See 
2360: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
2370: 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ode] documentati
2380: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
2390: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
23a0: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
23b0: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
23c0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
23d0: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
23e0: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
23f0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
2400: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  andle.** KEYWORD
2410: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
2420: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
2430: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
2440: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
2450: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
2460: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
2470: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
2480: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
2490: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
24a0: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
24b0: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
24c0: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
24d0: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
24e0: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
24f0: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
2500: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2510: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
2520: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2530: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
2540: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
2550: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
2560: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2570: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2580: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72  3_close_v2()] ar
2590: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  e its destructor
25a0: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  s.  There are ma
25b0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65  ny other.** inte
25c0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
25d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
25e0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
25f0: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2600: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
2610: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
2620: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
2630: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
2640: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
2650: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
2660: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
2670: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
2680: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
2690: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
26a0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
26b0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
26c0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
26d0: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
26e0: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
26f0: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
2700: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
2710: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
2720: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
2730: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
2740: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
2750: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
2760: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
2770: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
2780: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
2790: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
27a0: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
27b0: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
27c0: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
27d0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
27e0: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
27f0: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
2800: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
2810: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
2820: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
2830: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
2840: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
2850: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
2860: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
2870: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
2880: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
2890: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
28a0: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
28b0: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
28d0: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
28e0: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
28f0: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
2900: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
2910: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
2920: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
2930: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
2940: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
2950: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
2960: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2970: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
2980: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2990: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
29a0: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
29b0: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
29c0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
29d0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
29e0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
29f0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2a00: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2a10: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2a20: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2a30: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2a40: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2a50: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2a60: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2a70: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2a80: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2a90: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2aa0: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2ab0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2ac0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2ad0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2ae0: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2af0: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2b00: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2b10: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2b20: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2b30: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2b40: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2b50: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2b60: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2b70: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2b80: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2b90: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2ba0: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2bb0: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2bc0: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2bd0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2be0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2bf0: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2c00: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2c10: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2c20: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2c30: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2c40: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2c50: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2c60: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2c70: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2c80: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2c90: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2ca0: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2cb0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2cc0: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2cd0: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2ce0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2cf0: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2d00: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2d30: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2d40: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2d50: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2d60: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2d70: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2d80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2d90: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2da0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2db0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2dc0: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2dd0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2de0: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2df0: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
2e00: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2e10: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
2e20: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2e30: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
2e40: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
2e50: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
2e60: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2e70: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
2e80: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
2e90: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2ea0: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2eb0: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
2ec0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
2ed0: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
2ee0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
2ef0: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2f00: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
2f10: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
2f20: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
2f30: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
2f40: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
2f50: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
2f60: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
2f70: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
2f80: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
2f90: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
2fa0: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
2fb0: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2fc0: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
2fd0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
2fe0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2ff0: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3000: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3010: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3020: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3030: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
3040: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3050: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
3060: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
3070: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
3080: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
3090: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
30a0: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
30b0: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
30c0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
30d0: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
30e0: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
30f0: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3100: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3110: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3120: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3130: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
3140: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3150: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
3160: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
3170: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
3180: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
3190: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
31a0: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
31b0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
31c0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
31d0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
31e0: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
31f0: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3200: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3210: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3220: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3230: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
3240: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
3250: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
3260: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
3270: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
3280: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
3290: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
32a0: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
32b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
32c0: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
32d0: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
32e0: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
32f0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3300: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3310: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3320: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3330: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
3340: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
3350: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
3360: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
3370: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
3380: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
3390: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
33a0: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
33b0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
33c0: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
33d0: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
33e0: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
33f0: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
3400: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
3410: 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
3420: 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
3430: 4c 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  L sqlite3_close_
3440: 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  v2(sqlite3*);../
3450: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
3460: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
3470: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
3480: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
3490: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
34a0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
34b0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
34c0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
34d0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
34e0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
34f0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
3500: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3510: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
3520: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
3530: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
3540: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
3550: 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
3560: 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
3570: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e  qlite3_exec() in
3580: 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e  terface is a con
3590: 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72  venience wrapper
35a0: 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
35b0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
35c0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
35d0: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
35e0: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a  3_finalize()],.*
35f0: 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e  * that allows an
3600: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
3610: 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61  run multiple sta
3620: 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a  tements of SQL.*
3630: 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67  * without having
3640: 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66   to use a lot of
3650: 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20   C code. .**.** 
3660: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65  ^The sqlite3_exe
3670: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 75  c() interface ru
3680: 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ns zero or more 
3690: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a  UTF-8 encoded,.*
36a0: 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
36b0: 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  rate SQL stateme
36c0: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20  nts passed into 
36d0: 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
36e0: 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74  ,.** in the cont
36f0: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ext of the [data
3700: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3710: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 74   passed in as it
3720: 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  s 1st.** argumen
3730: 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  t.  ^If the call
3740: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66  back function of
3750: 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e   the 3rd argumen
3760: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3770: 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55  exec() is not NU
3780: 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69  LL, then it is i
3790: 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20  nvoked for each 
37a0: 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f  result row.** co
37b0: 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20  ming out of the 
37c0: 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74  evaluated SQL st
37d0: 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20  atements.  ^The 
37e0: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  4th argument to.
37f0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3800: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
3810: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
3820: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
3830: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3840: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3850: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3860: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3870: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3880: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3890: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
38a0: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
38b0: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
38c0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
38d0: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
38e0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
38f0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3900: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
3910: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
3920: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
3930: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3940: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3950: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3960: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3970: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3980: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3990: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39a0: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
39b0: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
39c0: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
39d0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
39e0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
39f0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
3a00: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
3a10: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
3a20: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
3a30: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3a40: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3a50: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3a60: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3a70: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3a80: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3a90: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3aa0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3ab0: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3ac0: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3ad0: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
3ae0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
3af0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
3b00: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
3b10: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3b20: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3b30: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3b40: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3b50: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3b60: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3b70: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3b80: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3b90: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3ba0: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3bb0: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3bc0: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3bd0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
3be0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3bf0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
3c00: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
3c10: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
3c20: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
3c30: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3c40: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3c50: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3c60: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3c70: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3c80: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3c90: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ca0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3cb0: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3cc0: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3cd0: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
3ce0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3cf0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3d00: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
3d10: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
3d20: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
3d30: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3d40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3d50: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3d60: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3d70: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3d80: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3d90: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3da0: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3db0: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3dc0: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3dd0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3de0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
3df0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
3e00: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
3e10: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3e20: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3e30: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3e40: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3e50: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3e60: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3e70: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3e80: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3e90: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3ea0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3eb0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3ec0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3ed0: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3ee0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3ef0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
3f00: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
3f10: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
3f20: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
3f30: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3f40: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3f50: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3f60: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3f70: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3f80: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3f90: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3fa0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3fb0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3fc0: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3fd0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
3fe0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3ff0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
4000: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4010: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
4020: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
4030: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
4040: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4050: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
4060: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
4070: 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64  not close the [d
4080: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4090: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
40a0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
40b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
40c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
40d0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
40e0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
40f0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4100: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
4110: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
4120: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
4130: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
4140: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4150: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
4160: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
4170: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
4180: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
4190: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
41a0: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
41b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
41c0: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
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 41 6e             /* An
41f0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
4200: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
4210: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4230: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
4240: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28  uated */.  int (
4250: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  *callback)(void*
4260: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
4270: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63  **),  /* Callbac
4280: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  k function */.  
4290: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73             /* 1s
42c0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  t argument to ca
42d0: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72  llback */.  char
42e0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
4310: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
4320: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
4330: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43  PI3REF: Result C
4340: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4350: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64  : {result code d
4360: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
4370: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
4380: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
4390: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
43a0: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
43b0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
43c0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
43d0: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
43e0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
43f0: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
4400: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4410: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4420: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4430: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65   See also: [exte
4440: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4450: 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f   definitions].*/
4460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4470: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
4480: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
4490: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
44a0: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
44b0: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
44c0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
44d0: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
44e0: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
44f0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4510: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
4520: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
4530: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
4540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4550: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
4560: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
4570: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
4580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
4590: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
45a0: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
45b0: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
45c0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
45d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
45e0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
45f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
4600: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4610: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
4620: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
4630: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
4640: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
4650: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4660: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
4670: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
4680: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
4690: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
46a0: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
46b0: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
46c0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
46d0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
46e0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
46f0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
4700: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
4710: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
4720: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
4730: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
4740: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
4750: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
4760: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
4770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4780: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
4790: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
47a0: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
47b0: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
47c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
47d0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
47e0: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
47f0: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
4800: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
4810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
4820: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
4830: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
4840: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
4850: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
4860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
4870: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
4880: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
4890: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
48a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48b0: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
48c0: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
48d0: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
48e0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
48f0: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
4900: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
4910: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
4920: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
4930: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
4940: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
4950: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
4960: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4970: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
4980: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
4990: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
49a0: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
49b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
49c0: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
49d0: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
49e0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
49f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a00: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
4a10: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
4a20: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
4a30: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
4a40: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
4a50: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
4a60: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
4a70: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
4a80: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
4a90: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
4aa0: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
4ab0: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
4ac0: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
4ad0: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
4ae0: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
4af0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b00: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
4b10: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
4b20: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
4b30: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4b40: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
4b50: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
4b60: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
4b70: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
4b80: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
4b90: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
4ba0: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
4bb0: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
4bc0: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
4bd0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
4be0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20  LITE_NOTICE     
4bf0: 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63   27   /* Notific
4c00: 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69  ations from sqli
4c10: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65  te3_log() */.#de
4c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
4c30: 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20  ING     28   /* 
4c40: 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71  Warnings from sq
4c50: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4c60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
4c70: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
4c80: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4c90: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
4ca0: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
4cb0: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
4cc0: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
4cd0: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4ce0: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
4cf0: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
4d00: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
4d10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4d20: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
4d30: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4d40: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
4d50: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4d60: 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  ions}.**.** In i
4d70: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4d80: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
4d90: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
4da0: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69  turn one of 30 i
4db0: 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c  nteger.** [resul
4dc0: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4dd0: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4de0: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4df0: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4e00: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4e10: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4e20: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4e30: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
4e40: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4e50: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4e60: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4e70: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4e80: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4e90: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4ea0: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4eb0: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4ec0: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4ed0: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4ee0: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
4ef0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
4f00: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
4f10: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
4f20: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
4f30: 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74  rors. These [ext
4f40: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4f50: 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20  es] are enabled 
4f60: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f  or disabled.** o
4f70: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65  n a per database
4f80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
4f90: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  s using the.** [
4fa0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
4fb0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
4fc0: 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65   API.  Or, the e
4fd0: 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72  xtended code for
4fe0: 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63  .** the most rec
4ff0: 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65  ent error can be
5000: 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a   obtained using.
5010: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
5020: 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e  nded_errcode()].
5030: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5040: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5050: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5060: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5070: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5080: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5090: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
50a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
50b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50c0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
50d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50e0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5100: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
5110: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5120: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
5130: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5140: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5150: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5160: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5170: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5180: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5190: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51a0: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
51b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51c0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
51d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51e0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5200: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
5210: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5220: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
5230: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5240: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5250: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5260: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5350: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5360: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5390: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
53a0: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5680: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5690: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
56a0: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
56b0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
56c0: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
56d0: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56e0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56f0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
5700: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
5710: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
5720: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
5730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5740: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5750: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5760: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5780: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5790: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
57a0: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
57b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
57c0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
57d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57e0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5800: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5810: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5820: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5830: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5840: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5850: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5860: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5880: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5890: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
58a0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
58b0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
58c0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
58d0: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58f0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5900: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5910: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
5920: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5930: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5940: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5950: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5960: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5970: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5990: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
59a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
59b0: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
59c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
59d0: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
59e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
59f0: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
5a00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a10: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
5a20: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a30: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
5a40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a50: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
5a60: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
5a70: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
5a80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a90: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5aa0: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
5ab0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5ac0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5ad0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5ae0: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
5af0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5b00: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
5b10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5b20: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
5b30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b40: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
5b50: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b60: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
5b70: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
5b80: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
5b90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ba0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5bb0: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
5bc0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5bd0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5be0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5bf0: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
5c00: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5c10: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
5c20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5c30: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
5c40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5c50: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
5c60: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c70: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
5c80: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5c90: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
5ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cb0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5cc0: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
5cd0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
5ce0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cf0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5d00: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
5d10: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
5d20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5d30: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
5d40: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
5d50: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
5d60: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d70: 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20  QLITE_AUTH_USER 
5d80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5d90: 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c  QLITE_AUTH | (1<
5da0: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5db0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5dc0: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5dd0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5de0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5df0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5e00: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5e10: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5e20: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5e30: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5e40: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5e50: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5e60: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5e70: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5e80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e90: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5ea0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5eb0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5ec0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5ed0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ee0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
5ef0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
5f00: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5f10: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5f20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f30: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
5f40: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5f50: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5f60: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f80: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5f90: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5fa0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5fb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fc0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5fd0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5fe0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5ff0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6000: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
6010: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
6020: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6040: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
6050: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
6060: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6070: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6080: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6090: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20  PEN_MEMORY      
60a0: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20       0x00000080 
60b0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
60c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
60d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60e0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
60f0: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
6100: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6120: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
6130: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
6140: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6160: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
6170: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
6180: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61a0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
61b0: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
61c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
61d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61e0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
61f0: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
6200: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6220: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
6230: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
6240: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6250: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6260: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
6270: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
6280: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6290: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
62a0: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
62b0: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
62c0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
62d0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
62e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
62f0: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
6300: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
6310: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6320: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6340: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
6350: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
6360: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6370: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6380: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6390: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
63a0: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
63b0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
63c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
63d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
63e0: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
63f0: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
6400: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6410: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6430: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
6440: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6450: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
6460: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
6470: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
6480: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
6490: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
64a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
64b0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
64c0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
64d0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
64e0: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
64f0: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
6500: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
6510: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
6520: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
6530: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
6540: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
6550: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6560: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
6570: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
6580: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6590: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
65a0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
65b0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
65c0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
65d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
65e0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
65f0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6600: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6610: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6620: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6630: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6640: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6650: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6660: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6670: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6680: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6690: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
66a0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
66b0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
66c0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
66d0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
66e0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
66f0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6700: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
6710: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
6720: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
6730: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6740: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6750: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6760: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
6770: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
6780: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
6790: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
67a0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
67b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
67c0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
67d0: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
67e0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
67f0: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
6800: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
6810: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
6820: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
6830: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
6840: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
6850: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
6860: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
6870: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
6880: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
6890: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
68a0: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
68b0: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
68c0: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
68d0: 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  nged.  The SQLIT
68e0: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
68f0: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a  BLE_WHEN_OPEN.**
6900: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74   flag indicate t
6910: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
6920: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
6930: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
6940: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6950: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6960: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6970: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6980: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6990: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
69a0: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
69b0: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
69c0: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
69d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
69e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6a00: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
6a10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a20: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
6a30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6a40: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6a50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6a60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6a70: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6a80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a90: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6aa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6ab0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ac0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ae0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
6af0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b00: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
6b10: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
6b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b30: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
6b40: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b50: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6b60: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b70: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6b80: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6b90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ba0: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6bb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6bc0: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6bd0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6be0: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
6bf0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
6c00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c10: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
6c20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
6c30: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c40: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6c50: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6c60: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6c70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6c80: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6c90: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6ca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6cb0: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20  OCAP_IMMUTABLE  
6cc0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6cd0: 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  002000../*.** CA
6ce0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6cf0: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6d00: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6d10: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6d20: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6d30: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6d40: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
6d50: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
6d60: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6d70: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6d80: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6d90: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6da0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6db0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6dc0: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6de0: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6df0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6e00: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6e10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6e20: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6e30: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6e40: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6e50: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
6e60: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6e70: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6e80: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6e90: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6ea0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6eb0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6ec0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6ed0: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6ee0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6ef0: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6f00: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6f10: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6f20: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6f30: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6f40: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6f50: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
6f60: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6f70: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6f80: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
6f90: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
6fa0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6fb0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6fc0: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6fd0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6fe0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6ff0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
7000: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
7010: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
7020: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
7030: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
7040: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
7050: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
7060: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
7070: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
7080: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7090: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
70a0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
70b0: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
70c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
70d0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
70e0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
70f0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
7100: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
7110: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
7120: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
7130: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
7140: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
7150: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
7160: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
7170: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
7180: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
7190: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
71a0: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
71b0: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
71c0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
71d0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
71e0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
71f0: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
7200: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
7210: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
7220: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
7230: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
7240: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
7250: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
7260: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
7270: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
7280: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
7290: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
72a0: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
72b0: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
72c0: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
72d0: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
72e0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
72f0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
7300: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
7310: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
7320: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
7330: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
7340: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
7350: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
7360: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
7370: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7380: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
7390: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
73a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
73b0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
73c0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
73d0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
73e0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
73f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7400: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
7410: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
7420: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
7430: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
7440: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
7450: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
7460: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
7470: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
7480: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
7490: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
74a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
74b0: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
74c0: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
74d0: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
74e0: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
74f0: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
7500: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
7510: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
7520: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
7530: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
7540: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
7550: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
7560: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
7570: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
7580: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
7590: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
75a0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
75b0: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
75c0: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
75d0: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
75e0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
75f0: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
7600: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
7610: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
7620: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
7630: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
7640: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
7650: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
7660: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
7670: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
7680: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7690: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
76a0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
76b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
76c0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
76d0: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
76e0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
76f0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7700: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
7710: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
7720: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
7730: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
7740: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
7750: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
7760: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7770: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7780: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7790: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
77a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
77b0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
77c0: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
77d0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
77e0: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
77f0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7800: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
7810: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
7820: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
7830: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7840: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
7850: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
7860: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7870: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7880: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7890: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
78a0: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
78b0: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
78c0: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
78d0: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
78e0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
78f0: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7900: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
7910: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
7920: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7930: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7940: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
7950: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7960: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7970: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7980: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7990: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
79a0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
79b0: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
79c0: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
79d0: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
79e0: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
79f0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7a00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7a10: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7a20: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
7a30: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7a40: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
7a50: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
7a60: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7a70: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7a80: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7a90: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7aa0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7ab0: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7ac0: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7ad0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7ae0: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7af0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7b00: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7b10: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7b20: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7b30: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7b40: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
7b50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7b60: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7b70: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7b80: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7b90: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7ba0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7bb0: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7bc0: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7bd0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7be0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7bf0: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7c00: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
7c10: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
7c20: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
7c30: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7c40: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
7c50: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
7c60: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7c70: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7c80: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7c90: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7ca0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7cb0: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7cc0: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7cd0: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7ce0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7cf0: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7d00: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7d10: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7d20: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7d30: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7d40: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7d50: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
7d60: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7d70: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7d80: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7d90: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7da0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7db0: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7dc0: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7dd0: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7de0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7df0: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7e00: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7e10: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7e20: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7e30: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7e40: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
7e50: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
7e60: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7e70: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7e80: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7e90: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7ea0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7eb0: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7ec0: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7ed0: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7ee0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7ef0: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7f00: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7f10: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7f20: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7f30: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7f40: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
7f50: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
7f60: 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   [file control o
7f70: 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66  pcodes | list of
7f80: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
7f90: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
7fa0: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
7fb0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
7fc0: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
7fd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
7fe0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
7ff0: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
8000: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
8010: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
8020: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
8030: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
8040: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
8050: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
8060: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
8070: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
8080: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
8090: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
80a0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
80b0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
80c0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
80d0: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
80e0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
80f0: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
8100: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
8110: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
8120: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
8130: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
8140: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
8150: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
8160: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8170: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
8180: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
8190: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
81a0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
81b0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
81c0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
81d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
81e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
81f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8200: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
8210: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8220: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
8230: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8240: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
8250: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8260: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
8270: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8280: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
8290: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
82a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
82b0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
82c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
82d0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
82e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
82f0: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
8300: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8310: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
8320: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
8330: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
8340: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
8350: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8360: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8370: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
8380: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
8390: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
83a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
83b0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
83c0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
83d0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
83e0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
83f0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
8400: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
8410: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
8420: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
8430: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
8440: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8450: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8460: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
8470: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
8480: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
8490: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
84a0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
84b0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
84c0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
84d0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
84e0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
84f0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
8500: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8510: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
8520: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8530: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
8540: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
8550: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
8560: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
8570: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
8580: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
8590: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
85a0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
85b0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
85c0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
85d0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
85e0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
85f0: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
8600: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
8610: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8620: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
8630: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
8640: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
8650: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8660: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
8670: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
8680: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
8690: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
86a0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
86b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
86c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
86d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
86e0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
86f0: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
8700: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
8710: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8720: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
8730: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
8740: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8750: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8760: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8770: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8780: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
8790: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
87a0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
87b0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
87c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
87d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
87e0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
87f0: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
8800: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8810: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
8820: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8830: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8840: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8850: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8860: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8870: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8880: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8890: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
88a0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
88b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
88c0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
88d0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
88e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88f0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
8900: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
8910: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
8920: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8930: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8940: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8950: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8960: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8970: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8980: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8990: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
89a0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
89b0: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
89c0: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
89d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
89e0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
89f0: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
8a00: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
8a10: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
8a20: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8a30: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8a40: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8a50: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8a60: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8a70: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8a80: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8a90: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
8aa0: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
8ab0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8ac0: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
8ad0: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
8ae0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
8af0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8b00: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8b10: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
8b20: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8b30: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8b40: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
8b50: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
8b60: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
8b70: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8b80: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8b90: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8ba0: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8bb0: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8bc0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65   KEYWORDS: {file
8bd0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8be0: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  } {file control 
8bf0: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  opcode}.**.** Th
8c00: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8c10: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8c20: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8c30: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
8c40: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
8c50: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8c60: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8c70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8c80: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8c90: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rface..**.** <ul
8ca0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
8cb0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8cc0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8cd0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8ce0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8cf0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8d00: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8d10: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8d20: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8d30: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8d40: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8d50: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8d60: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8d70: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8d80: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8d90: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8da0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8db0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8dc0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8dd0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8de0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8df0: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8e00: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8e10: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8e20: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8e30: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73  g testing and is
8e40: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
8e50: 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  when the SQLITE_
8e60: 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  TEST.** compile-
8e70: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75  time option is u
8e80: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  sed..**.** <li>[
8e90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8ea0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8eb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8ec0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8ed0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
8ee0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8ef0: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8f00: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8f20: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8f30: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8f40: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8f50: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8f60: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8f70: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8f80: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8f90: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8fa0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8fb0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8fc0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8fd0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8fe0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8ff0: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
9000: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
9010: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
9020: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
9030: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9040: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9050: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
9060: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
9070: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
9080: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
9090: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
90a0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
90b0: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
90c0: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
90d0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
90e0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
90f0: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
9100: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
9110: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9120: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
9130: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
9140: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
9150: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
9160: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
9170: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
9180: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
9190: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
91a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
91b0: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
91c0: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
91d0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
91e0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
91f0: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
9200: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
9210: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
9220: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
9230: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9240: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9250: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9270: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9280: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9290: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
92a0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
92b0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
92c0: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
92d0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
92e0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
92f0: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
9300: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9310: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
9320: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
9330: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
9340: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9350: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
9360: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
9370: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9380: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9390: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
93a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
93b0: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
93c0: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
93d0: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
93e0: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
93f0: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
9400: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
9410: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
9420: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
9430: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
9440: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
9450: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9460: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
9470: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9480: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9490: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
94a0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
94b0: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
94c0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
94d0: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
94e0: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
94f0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9500: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
9510: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
9520: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
9530: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
9540: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
9550: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
9560: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
9570: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9580: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
9590: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
95a0: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
95b0: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
95c0: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
95d0: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
95e0: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
95f0: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
9600: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
9610: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
9620: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9630: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
9640: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9650: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9660: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
9670: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9680: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9690: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
96a0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
96b0: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
96c0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
96d0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
96e0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
96f0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9700: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9710: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
9720: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
9730: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9740: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
9750: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9760: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
9770: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
9780: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
9790: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
97a0: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
97b0: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
97c0: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
97d0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
97e0: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
97f0: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
9800: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
9810: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9820: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9830: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
9840: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
9850: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9860: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9870: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9880: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9890: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
98a0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
98b0: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
98c0: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
98d0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
98e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
98f0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
9900: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9910: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9920: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
9930: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
9940: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
9950: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
9960: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
9970: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9980: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9990: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
99a0: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
99b0: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
99c0: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
99d0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
99e0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
99f0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
9a00: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
9a10: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
9a20: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9a30: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9a40: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9a50: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9a60: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9a70: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9a80: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9a90: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
9aa0: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
9ab0: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
9ac0: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
9ad0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
9ae0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
9af0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9b00: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
9b10: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
9b20: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9b30: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9b40: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9b50: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9b60: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9b70: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9b80: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9b90: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
9ba0: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
9bb0: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
9bc0: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
9bd0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
9be0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
9bf0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
9c00: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
9c10: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
9c20: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9c30: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9c40: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9c50: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9c60: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9c70: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9c80: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9c90: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
9ca0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
9cb0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
9cc0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
9cd0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
9ce0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
9cf0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9d00: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9d10: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9d20: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9d30: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9d40: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9d50: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9d60: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9d70: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9d80: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9d90: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
9da0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
9db0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
9dc0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
9dd0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
9de0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
9df0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
9e00: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
9e10: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
9e20: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
9e30: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
9e40: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
9e50: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
9e60: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9e70: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
9e80: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
9e90: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
9ea0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
9eb0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
9ec0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
9ed0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
9ee0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
9ef0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
9f00: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
9f10: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
9f20: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
9f30: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
9f40: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
9f50: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
9f60: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
9f70: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
9f80: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9f90: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
9fa0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
9fb0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
9fc0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
9fd0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
9fe0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
9ff0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a000: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a010: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a020: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a030: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a040: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a050: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
a060: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
a070: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
a080: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
a090: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a0a0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a0b0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a0c0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a0d0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
a0e0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a0f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a100: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a110: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a120: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a130: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a140: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
a150: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
a160: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
a170: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
a180: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
a190: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
a1a0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
a1b0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
a1c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
a1d0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a1e0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
a1f0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
a200: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
a210: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
a220: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a230: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a240: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a250: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a260: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a270: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a280: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a290: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
a2a0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
a2b0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
a2c0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
a2d0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a2e0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a2f0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a300: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a310: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a320: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a330: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a340: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
a350: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a360: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
a370: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
a380: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
a390: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
a3a0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
a3b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
a3c0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
a3d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
a3e0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
a3f0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
a400: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
a410: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
a420: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
a430: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
a440: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
a450: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
a460: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a470: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a480: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a490: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a4a0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
a4b0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
a4c0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
a4d0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
a4e0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
a4f0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
a500: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
a510: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
a520: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
a530: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
a540: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
a550: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
a560: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
a570: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
a580: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
a590: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
a5a0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
a5b0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
a5c0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a5d0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
a5e0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
a5f0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
a600: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
a610: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
a620: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
a630: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
a640: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
a650: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
a660: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
a670: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
a680: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
a690: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
a6a0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
a6b0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
a6c0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
a6d0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
a6e0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
a6f0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a700: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a710: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a720: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a730: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a740: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
a750: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
a760: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
a770: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
a780: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a790: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
a7a0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
a7b0: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
a7c0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
a7d0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
a7e0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
a7f0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
a800: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
a810: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
a820: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
a830: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a840: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a850: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
a860: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
a870: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
a880: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
a890: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
a8a0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
a8b0: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
a8c0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
a8d0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
a8e0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
a8f0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
a900: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
a910: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
a920: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
a930: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
a940: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a950: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a960: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
a970: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
a980: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
a990: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
a9a0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
a9b0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
a9c0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
a9d0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
a9e0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
a9f0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
aa00: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
aa10: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
aa20: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
aa30: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
aa40: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
aa50: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
aa60: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aa70: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
aa80: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
aa90: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
aaa0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
aab0: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
aac0: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
aad0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aae0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
aaf0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
ab00: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
ab10: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
ab20: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
ab30: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
ab40: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
ab50: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
ab60: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
ab70: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
ab80: 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73  statement if res
ab90: 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55  ult string is NU
aba0: 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75  LL, or that retu
abb0: 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66  rns a copy.** of
abc0: 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69   the result stri
abd0: 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ng if the string
abe0: 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a   is non-NULL..**
abf0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
ac00: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ac10: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
ac20: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
ac30: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
ac40: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
ac50: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
ac60: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
ac70: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
ac80: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
ac90: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
aca0: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
acb0: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
acc0: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
acd0: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
ace0: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
acf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ad00: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
ad10: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
ad20: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
ad30: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
ad40: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
ad50: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
ad60: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
ad70: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
ad80: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
ad90: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ada0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
adb0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
adc0: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
add0: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
ade0: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
adf0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
ae00: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
ae10: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
ae20: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
ae30: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
ae40: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
ae50: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
ae60: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
ae70: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
ae80: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
ae90: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
aea0: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
aeb0: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
aec0: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
aed0: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
aee0: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
aef0: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
af00: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
af10: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
af20: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
af30: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
af40: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
af50: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
af60: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
af70: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
af80: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
af90: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
afa0: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
afb0: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
afc0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
afd0: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
afe0: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
aff0: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
b000: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
b010: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
b020: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
b030: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
b040: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
b050: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b060: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
b070: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
b080: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
b090: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b0a0: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
b0b0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
b0c0: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
b0d0: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
b0e0: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
b0f0: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
b100: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
b110: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
b120: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b130: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
b140: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
b150: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
b160: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
b170: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
b180: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
b190: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
b1a0: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
b1b0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
b1c0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
b1d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
b1e0: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
b1f0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
b200: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
b210: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
b220: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
b230: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
b240: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b250: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
b260: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b270: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
b280: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b290: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
b2a0: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
b2b0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b2c0: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
b2d0: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
b2e0: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
b2f0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b300: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
b310: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
b320: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
b330: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
b340: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
b350: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
b360: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
b370: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
b380: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
b390: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
b3a0: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
b3b0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
b3c0: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
b3d0: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
b3e0: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
b3f0: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
b400: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
b410: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
b420: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
b430: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
b440: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
b450: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
b460: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
b470: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
b480: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
b490: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
b4a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b4b0: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
b4c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b4d0: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
b4e0: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
b4f0: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
b500: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
b510: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
b520: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
b530: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
b540: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
b550: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b560: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
b570: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
b580: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
b590: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
b5a0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
b5b0: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
b5c0: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
b5d0: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
b5e0: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
b5f0: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
b600: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
b610: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
b620: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
b630: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
b640: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
b650: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b660: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b670: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b680: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
b690: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
b6a0: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
b6b0: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
b6c0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b6d0: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
b6e0: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
b6f0: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
b700: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
b710: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
b720: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
b730: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
b740: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
b750: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
b760: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
b770: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b780: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
b790: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
b7a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b7b0: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
b7c0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
b7d0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
b7e0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
b7f0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
b800: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
b810: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
b820: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
b830: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
b840: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
b850: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
b860: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
b870: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
b880: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
b890: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
b8a0: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
b8b0: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
b8c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b8d0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a  TL_WAL_BLOCK]].*
b8e0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b8f0: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69  NTL_WAL_BLOCK] i
b900: 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68  s a signal to th
b910: 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74  e VFS layer that
b920: 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20   it might.** be 
b930: 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20  advantageous to 
b940: 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78  block on the nex
b950: 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68  t WAL lock if th
b960: 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d  e lock is not im
b970: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61  mediately.** ava
b980: 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c  ilable.  The WAL
b990: 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65   subsystem issue
b9a0: 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75  s this signal du
b9b0: 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72  ring rare.** cir
b9c0: 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72  cumstances in or
b9d0: 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f  der to fix a pro
b9e0: 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69  blem with priori
b9f0: 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  ty inversion..**
ba00: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
ba10: 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d  ould <em>not</em
ba20: 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d  > use this file-
ba30: 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c  control..**.** <
ba40: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ba50: 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68  L_ZIPVFS]].** Th
ba60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ba70: 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69  ZIPVFS] opcode i
ba80: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
ba90: 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c   zipvfs only. Al
baa0: 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73  l other.** VFS s
bab0: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c  hould return SQL
bac0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72  ITE_NOTFOUND for
bad0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a   this opcode..**
bae0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
baf0: 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20  _FCNTL_RBU]].** 
bb00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bb10: 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73  L_RBU] opcode is
bb20: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
bb30: 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
bb40: 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52  used by.** the R
bb50: 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c  BU extension onl
bb60: 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46  y.  All other VF
bb70: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
bb80: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
bb90: 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f  for.** this opco
bba0: 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  de.  .** </ul>.*
bbb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
bbc0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
bbd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
bbe0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bbf0: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
bc00: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a  OXYFILE       2.
bc10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bc20: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
bc30: 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23  XYFILE       3.#
bc40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bc50: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  NTL_LAST_ERRNO  
bc60: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
bc70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bc80: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
bc90: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
bca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bcb0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
bcc0: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
bcd0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bce0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
bcf0: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
bd00: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bd10: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
bd20: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
bd30: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
bd40: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
bd50: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
bd60: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
bd70: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
bd80: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
bd90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
bda0: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
bdb0: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
bdc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
bdd0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
bde0: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
bdf0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
be00: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
be10: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
be20: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
be30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
be40: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
be50: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
be60: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
be70: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
be80: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
be90: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
bea0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
beb0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
bec0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
bed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bee0: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20  FCNTL_TRACE     
bef0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a               19.
bf00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bf10: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20  CNTL_HAS_MOVED  
bf20: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23              20.#
bf30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bf40: 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20  NTL_SYNC        
bf50: 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64             21.#d
bf60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf70: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
bf80: 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65  WO        22.#de
bf90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bfa0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
bfb0: 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66  LE       23.#def
bfc0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bfd0: 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20  _WAL_BLOCK      
bfe0: 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69          24.#defi
bff0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c000: 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20  ZIPVFS          
c010: 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e         25.#defin
c020: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  e SQLITE_FCNTL_R
c030: 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20  BU              
c040: 20 20 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70        26../* dep
c050: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
c060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c070: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c080: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
c090: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
c0a0: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
c0b0: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
c0c0: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c0d0: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
c0e0: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c0f0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
c100: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
c110: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
c120: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
c130: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
c140: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
c150: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
c160: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
c170: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
c180: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
c190: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
c1a0: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
c1b0: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
c1c0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
c1d0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
c1e0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
c1f0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
c200: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
c210: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
c220: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
c230: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c240: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
c250: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
c260: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c270: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
c280: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c290: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
c2a0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
c2b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c2c0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
c2d0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
c2e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
c2f0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
c300: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
c310: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
c320: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
c330: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
c340: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
c350: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
c360: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
c370: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
c380: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
c390: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
c3a0: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
c3b0: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
c3c0: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
c3d0: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
c3e0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
c3f0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
c400: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
c410: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
c420: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
c430: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
c440: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
c450: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
c460: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
c470: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
c480: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
c490: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
c4a0: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
c4b0: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
c4c0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
c4d0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
c4e0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
c4f0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
c500: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
c510: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
c520: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
c530: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
c540: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
c550: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
c560: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
c570: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
c580: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
c590: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
c5a0: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
c5b0: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
c5c0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
c5d0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
c5e0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
c5f0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
c600: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
c610: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
c620: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
c630: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
c640: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c650: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
c660: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
c670: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
c680: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
c690: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
c6a0: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
c6b0: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
c6c0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
c6d0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
c6e0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
c6f0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
c700: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
c710: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
c720: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
c730: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
c740: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
c750: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
c760: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
c770: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
c780: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
c790: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
c7a0: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
c7b0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
c7c0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
c7d0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
c7e0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
c7f0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
c800: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
c810: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
c820: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
c830: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
c840: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
c850: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
c860: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
c870: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
c880: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
c890: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
c8a0: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
c8b0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
c8c0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
c8d0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
c8e0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
c8f0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
c900: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
c910: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
c920: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
c930: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
c940: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
c950: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
c960: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
c970: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
c980: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
c990: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
c9a0: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
c9b0: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
c9c0: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
c9d0: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
c9e0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
c9f0: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
ca00: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
ca10: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
ca20: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
ca30: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
ca40: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
ca50: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
ca60: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
ca70: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
ca80: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
ca90: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
caa0: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
cab0: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
cac0: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
cad0: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
cae0: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
caf0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
cb00: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
cb10: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
cb20: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
cb30: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
cb40: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
cb50: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
cb60: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
cb70: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
cb80: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
cb90: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
cba0: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
cbb0: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
cbc0: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
cbd0: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
cbe0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
cbf0: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
cc00: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
cc10: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
cc20: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
cc30: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
cc40: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
cc50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
cc60: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
cc70: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
cc80: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
cc90: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
cca0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
ccb0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
ccc0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
ccd0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
cce0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
ccf0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
cd00: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
cd10: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
cd20: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
cd30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
cd40: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
cd50: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
cd60: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
cd70: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
cd80: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
cd90: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
cda0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
cdb0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
cdc0: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
cdd0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
cde0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
cdf0: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
ce00: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
ce10: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
ce20: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
ce30: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
ce40: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
ce50: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
ce60: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ce70: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ce80: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
ce90: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
cea0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
ceb0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
cec0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
ced0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
cee0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
cef0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
cf00: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
cf10: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
cf20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
cf30: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
cf40: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
cf50: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
cf60: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
cf70: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
cf80: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
cf90: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
cfa0: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
cfb0: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
cfc0: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
cfd0: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
cfe0: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
cff0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
d000: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
d010: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
d020: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
d030: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
d040: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
d050: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
d060: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
d070: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
d080: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
d090: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
d0a0: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
d0b0: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
d0c0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
d0d0: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
d0e0: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
d0f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
d100: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
d110: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
d120: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
d130: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
d140: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
d150: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
d160: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
d170: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
d180: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
d190: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
d1a0: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
d1b0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
d1c0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
d1d0: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
d1e0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
d1f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d200: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
d210: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
d220: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
d230: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
d240: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
d250: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
d260: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
d270: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
d280: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
d290: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
d2a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d2b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
d2c0: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
d2d0: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
d2e0: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
d2f0: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
d300: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
d310: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
d320: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
d330: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
d340: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
d350: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
d360: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
d370: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
d380: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
d390: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
d3a0: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
d3b0: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
d3c0: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
d3d0: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
d3e0: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
d3f0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
d400: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
d410: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
d420: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
d430: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
d440: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
d450: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
d460: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
d470: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
d480: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
d490: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
d4a0: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
d4b0: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
d4c0: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
d4d0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
d4e0: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
d4f0: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
d500: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
d510: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
d520: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
d530: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
d540: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
d550: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
d560: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
d570: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
d580: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
d590: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
d5a0: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
d5b0: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
d5c0: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
d5d0: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
d5e0: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
d5f0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
d600: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
d610: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
d620: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
d630: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
d640: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
d650: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
d660: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
d670: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
d680: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
d690: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
d6a0: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
d6b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
d6c0: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
d6d0: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
d6e0: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
d6f0: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
d700: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
d710: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
d720: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
d730: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
d740: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
d750: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
d760: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
d770: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
d780: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
d790: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
d7a0: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
d7b0: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
d7c0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
d7d0: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
d7e0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
d7f0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
d800: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
d810: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
d820: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
d830: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
d840: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
d850: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
d860: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
d870: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
d880: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
d890: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
d8a0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
d8b0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
d8c0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
d8d0: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
d8e0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
d8f0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
d900: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
d910: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
d920: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
d930: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
d940: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
d950: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
d960: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
d970: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
d980: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
d990: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
d9a0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
d9b0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
d9c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
d9d0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
d9e0: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
d9f0: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
da00: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
da10: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
da20: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
da30: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
da40: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
da50: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
da60: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
da70: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
da80: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
da90: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
daa0: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
dab0: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
dac0: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
dad0: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
dae0: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
daf0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
db00: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
db10: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
db20: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
db30: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
db40: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
db50: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
db60: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
db70: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
db80: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
db90: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
dba0: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
dbb0: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
dbc0: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
dbd0: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
dbe0: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
dbf0: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
dc00: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
dc10: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
dc20: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
dc30: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
dc40: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
dc50: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
dc60: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
dc70: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
dc80: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
dc90: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
dca0: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
dcb0: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
dcc0: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
dcd0: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
dce0: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
dcf0: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
dd00: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
dd10: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
dd20: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
dd30: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
dd40: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
dd50: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
dd60: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
dd70: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
dd80: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
dd90: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
dda0: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
ddb0: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
ddc0: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
ddd0: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
dde0: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
ddf0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
de00: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
de10: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
de20: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
de30: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
de40: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
de50: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
de60: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
de70: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
de80: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
de90: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
dea0: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
deb0: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
dec0: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
ded0: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
dee0: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
def0: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
df00: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
df10: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
df20: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
df30: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
df40: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
df50: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
df60: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
df70: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
df80: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
df90: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
dfa0: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
dfb0: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
dfc0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
dfd0: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
dfe0: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
dff0: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
e000: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
e010: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
e020: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
e030: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
e040: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
e050: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
e060: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
e070: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
e080: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
e090: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
e0a0: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
e0b0: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
e0c0: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
e0d0: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
e0e0: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
e0f0: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
e100: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
e110: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
e120: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
e130: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
e140: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
e150: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
e160: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
e170: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
e180: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
e190: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
e1a0: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
e1b0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
e1c0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
e1d0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
e1e0: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
e1f0: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
e200: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
e210: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
e220: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
e230: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
e240: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
e250: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
e260: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
e270: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
e280: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
e290: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
e2a0: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
e2b0: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
e2c0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
e2d0: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
e2e0: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
e2f0: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
e300: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
e310: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
e320: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
e330: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
e340: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
e350: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e360: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e370: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
e380: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
e390: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
e3a0: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
e3b0: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
e3c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e3d0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e3e0: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
e3f0: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
e400: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e410: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e420: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
e430: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
e440: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
e450: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e460: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e470: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
e480: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
e490: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
e4a0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e4b0: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
e4c0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
e4d0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
e4e0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
e4f0: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
e500: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
e510: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
e520: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
e530: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
e540: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
e550: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
e560: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
e570: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
e580: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
e590: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
e5a0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
e5b0: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
e5c0: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
e5d0: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
e5e0: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
e5f0: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
e600: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
e610: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
e620: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
e630: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
e640: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e650: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e660: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
e670: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
e680: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
e690: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
e6a0: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
e6b0: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
e6c0: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
e6d0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
e6e0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
e6f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
e700: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
e710: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
e720: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
e730: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
e740: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e750: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
e760: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
e770: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
e780: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
e790: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e7a0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e7b0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
e7c0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e7d0: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
e7e0: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
e7f0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e800: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e810: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
e820: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
e830: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
e840: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e850: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
e860: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e870: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e880: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
e890: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
e8a0: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
e8b0: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
e8c0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
e8d0: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
e8e0: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
e8f0: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
e900: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
e910: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
e920: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
e930: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
e940: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
e950: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
e960: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
e970: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
e980: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
e990: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
e9a0: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
e9b0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
e9c0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
e9d0: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
e9e0: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
e9f0: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
ea00: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
ea10: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
ea20: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
ea30: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
ea40: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
ea50: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
ea60: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
ea70: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
ea80: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
ea90: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
eaa0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
eab0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
eac0: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
ead0: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
eae0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
eaf0: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
eb00: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
eb10: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
eb20: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
eb30: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
eb40: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
eb50: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
eb60: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
eb70: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
eb80: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
eb90: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
eba0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
ebb0: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
ebc0: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
ebd0: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
ebe0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
ebf0: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
ec00: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
ec10: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ec20: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
ec30: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
ec40: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
ec50: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ec60: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
ec70: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
ec80: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
ec90: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
eca0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
ecb0: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
ecc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ecd0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
ece0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
ecf0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ed00: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
ed10: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
ed20: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
ed30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ed40: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
ed50: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
ed60: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
ed70: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
ed80: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
ed90: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
eda0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
edb0: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
edc0: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
edd0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
ede0: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
edf0: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
ee00: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
ee10: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
ee20: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
ee30: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
ee40: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
ee50: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
ee60: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
ee70: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
ee80: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
ee90: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
eea0: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
eeb0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
eec0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
eed0: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
eee0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
eef0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
ef00: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
ef10: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
ef20: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
ef30: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
ef40: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
ef50: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
ef60: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
ef70: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
ef80: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
ef90: 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72  iven on the corr
efa0: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
efb0: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
efc0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
efd0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
efe0: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
eff0: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
f000: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
f010: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
f020: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
f030: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
f040: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
f050: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
f060: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
f070: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
f080: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
f090: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
f0a0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
f0b0: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
f0c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f0d0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
f0e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f0f0: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
f100: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
f110: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f120: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
f130: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
f140: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
f150: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
f160: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
f170: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
f180: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
f190: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
f1a0: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
f1b0: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
f1c0: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
f1d0: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
f1e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f1f0: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
f200: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
f210: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
f220: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
f230: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
f240: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f250: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
f260: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
f270: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
f280: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
f290: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
f2a0: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
f2b0: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
f2c0: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
f2d0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
f2e0: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
f2f0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
f300: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
f310: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
f320: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
f330: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
f340: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
f350: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
f360: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
f370: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
f380: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
f390: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
f3a0: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
f3b0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
f3c0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
f3d0: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
f3e0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
f3f0: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
f400: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
f410: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f420: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
f430: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
f440: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
f450: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
f460: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
f470: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f480: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
f490: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
f4a0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
f4b0: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
f4c0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
f4d0: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
f4e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
f4f0: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
f500: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
f510: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
f520: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
f530: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
f540: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f550: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
f560: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
f570: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
f580: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f590: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
f5a0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
f5b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
f5c0: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
f5d0: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
f5e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f5f0: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
f600: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
f610: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
f620: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
f630: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
f640: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
f650: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
f660: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f670: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
f680: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
f690: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f6a0: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
f6b0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f6c0: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
f6d0: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
f6e0: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
f6f0: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
f700: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
f710: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
f720: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
f730: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
f740: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
f750: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
f760: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
f770: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
f780: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
f790: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
f7a0: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
f7b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
f7c0: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
f7d0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
f7e0: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
f7f0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
f800: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
f810: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
f820: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
f830: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
f840: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
f850: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
f860: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
f870: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
f880: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f890: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
f8a0: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
f8b0: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
f8c0: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
f8d0: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
f8e0: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
f8f0: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
f900: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
f910: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
f920: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
f930: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
f940: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f950: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
f960: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
f970: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
f980: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
f990: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
f9a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
f9b0: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
f9c0: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
f9d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f9e0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
f9f0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
fa00: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
fa10: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
fa20: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
fa30: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
fa40: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
fa50: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
fa60: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
fa70: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
fa80: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
fa90: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
faa0: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
fab0: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
fac0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
fad0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
fae0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
faf0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
fb00: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
fb10: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
fb20: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
fb30: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
fb40: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
fb50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
fb60: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
fb70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
fb80: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
fb90: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
fba0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fbb0: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
fbc0: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
fbd0: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
fbe0: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
fbf0: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
fc00: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fc10: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
fc20: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
fc30: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
fc40: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
fc50: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
fc60: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
fc70: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
fc80: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
fc90: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
fca0: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
fcb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
fcc0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
fcd0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
fce0: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
fcf0: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
fd00: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
fd10: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
fd20: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
fd30: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
fd40: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
fd50: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
fd60: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
fd70: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
fd80: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
fd90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
fda0: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
fdb0: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
fdc0: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
fdd0: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
fde0: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
fdf0: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
fe00: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
fe10: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
fe20: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
fe30: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
fe40: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
fe50: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
fe60: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
fe70: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
fe80: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
fe90: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
fea0: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
feb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
fec0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
fed0: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
fee0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
fef0: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
ff00: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
ff10: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
ff20: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ff30: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
ff40: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
ff50: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
ff60: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
ff70: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
ff80: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
ff90: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
ffa0: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
ffb0: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
ffc0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
ffd0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ffe0: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
fff0: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
10000 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
10010 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
10020 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
10030 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
10040 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10050 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
10060 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
10070 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
10080 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
10090 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
100a0 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
100b0 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
100c0 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
100d0 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
100e0 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
100f0 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
10100 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
10110 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
10120 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
10130 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
10140 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
10150 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
10160 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
10170 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10180 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
10190 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
101a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
101b0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
101c0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
101d0 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
101e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
101f0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
10200 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
10210 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
10220 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c   failure..*/.SQL
10230 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
10240 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
10250 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
10260 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
10270 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
10280 4c 4c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  LL sqlite3_shutd
10290 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  own(void);.SQLIT
102a0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
102b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
102c0 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
102d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
102e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
102f0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
10300 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
10310 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
10320 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
10330 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
10340 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10350 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
10360 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
10370 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10380 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
10390 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
103a0 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
103b0 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
103c0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
103d0 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
103e0 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
103f0 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
10400 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
10410 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
10420 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
10430 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
10440 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
10450 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
10460 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
10470 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
10480 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
10490 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
104a0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
104b0 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
104c0 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
104d0 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
104e0 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
104f0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10500 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
10510 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
10520 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
10530 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
10540 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
10550 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
10560 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
10570 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
10580 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
10590 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
105a0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
105b0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
105c0 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
105d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
105e0 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
105f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10600 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
10610 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
10620 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
10630 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
10640 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
10650 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
10660 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
10670 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
10680 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
10690 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
106a0 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
106b0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
106c0 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
106d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
106e0 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
106f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
10700 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10710 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10720 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
10730 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
10740 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
10750 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
10760 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
10770 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
10780 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
10790 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
107a0 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
107b0 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
107c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
107d0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
107e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
107f0 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
10800 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
10810 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
10820 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
10830 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
10840 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
10850 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
10860 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
10870 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
10880 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
10890 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
108a0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
108b0 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  e]..*/.SQLITE_AP
108c0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45  I int SQLITE_CDE
108d0 43 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  CL sqlite3_confi
108e0 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
108f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10900 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
10910 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
10920 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
10930 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10940 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
10950 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10960 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
10970 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
10980 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
10990 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
109a0 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
109b0 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
109c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
109d0 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
109e0 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
109f0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
10a00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10a10 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
10a20 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10a30 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
10a40 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
10a50 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
10a60 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
10a70 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
10a80 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10a90 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
10aa0 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
10ab0 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
10ac0 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
10ad0 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
10ae0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
10af0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
10b00 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
10b10 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10b20 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
10b30 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
10b40 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
10b50 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
10b60 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10b70 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
10b80 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
10b90 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
10ba0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
10bb0 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  cessful..*/.SQLI
10bc0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
10bd0 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f  E_CDECL sqlite3_
10be0 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
10bf0 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
10c00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10c10 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
10c20 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
10c30 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
10c40 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
10c50 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
10c60 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
10c70 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
10c80 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
10c90 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
10ca0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
10cb0 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
10cc0 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
10cd0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
10ce0 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
10cf0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
10d00 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10d10 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
10d20 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10d30 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
10d40 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10d50 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
10d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10d70 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
10d80 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
10d90 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
10da0 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
10db0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
10dc0 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
10dd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
10de0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
10df0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
10e00 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
10e10 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
10e20 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
10e30 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
10e40 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
10e50 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
10e60 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
10e70 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
10e80 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
10e90 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
10ea0 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
10eb0 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
10ec0 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
10ed0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
10ee0 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
10ef0 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
10f00 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
10f10 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
10f20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
10f30 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
10f40 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
10f50 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
10f60 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
10f70 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
10f80 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
10f90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10fa0 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
10fb0 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
10fc0 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
10fd0 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
10fe0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
10ff0 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
11000 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
11010 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
11020 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
11030 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
11040 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
11050 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
11060 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
11070 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
11080 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
11090 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
110a0 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
110b0 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
110c0 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
110d0 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
110e0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
110f0 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
11100 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
11110 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
11120 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
11130 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
11140 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11150 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
11160 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
11170 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
11180 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
11190 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
111a0 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
111b0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
111c0 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
111d0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
111e0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
111f0 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
11200 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
11210 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
11220 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
11230 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
11240 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
11250 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
11260 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
11270 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
11280 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
11290 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
112a0 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
112b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
112c0 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
112d0 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
112e0 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
112f0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
11300 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
11310 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
11320 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
11330 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
11340 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
11350 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
11360 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
11370 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
11380 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
11390 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
113a0 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
113b0 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
113c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
113d0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
113e0 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
113f0 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
11400 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
11410 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
11420 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
11430 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
11440 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
11450 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
11460 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
11470 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
11480 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
11490 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
114a0 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
114b0 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
114c0 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
114d0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
114e0 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
114f0 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
11500 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
11510 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
11520 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
11530 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
11540 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
11550 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
11560 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
11570 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
11580 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
11590 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
115a0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
115b0 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
115c0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
115d0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
115e0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
115f0 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
11600 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
11610 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
11620 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
11630 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
11640 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
11650 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
11660 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
11670 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
11680 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
11690 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
116a0 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
116b0 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
116c0 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
116d0 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
116e0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
116f0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
11700 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
11710 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
11720 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11730 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
11740 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
11750 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
11760 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
11770 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
11780 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
11790 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
117a0 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
117b0 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
117c0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
117d0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
117e0 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
117f0 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
11800 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
11810 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
11820 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
11830 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
11840 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
11850 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
11860 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
11870 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
11880 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
11890 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
118a0 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
118b0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
118c0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
118d0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
118e0 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
118f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
11900 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
11910 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11920 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
11930 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
11940 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
11950 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
11960 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
11970 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
11980 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
11990 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
119a0 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
119b0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
119c0 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
119d0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
119e0 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
119f0 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
11a00 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
11a10 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
11a20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
11a30 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
11a40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
11a50 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
11a60 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
11a70 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
11a80 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
11a90 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
11aa0 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
11ab0 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
11ac0 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
11ad0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11ae0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
11af0 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
11b00 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
11b10 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
11b20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
11b30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11b40 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
11b50 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
11b60 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
11b70 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
11b80 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
11b90 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
11ba0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
11bb0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11bc0 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
11bd0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
11be0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
11bf0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
11c00 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11c10 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
11c20 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11c30 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
11c40 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
11c50 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
11c60 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
11c70 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11c80 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
11c90 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
11ca0 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
11cb0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
11cc0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
11cd0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
11ce0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
11cf0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
11d00 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
11d10 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
11d20 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
11d30 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
11d40 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
11d50 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
11d60 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
11d70 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11d80 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
11d90 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
11da0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11db0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
11dc0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11dd0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
11de0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
11df0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
11e00 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
11e10 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
11e20 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
11e30 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
11e40 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
11e50 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
11e60 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
11e70 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
11e80 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
11e90 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
11ea0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
11eb0 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
11ec0 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
11ed0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11ee0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11ef0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11f00 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11f10 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11f20 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11f30 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11f40 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
11f50 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
11f60 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
11f70 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
11f80 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
11f90 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
11fa0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
11fb0 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
11fc0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
11fd0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
11fe0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11ff0 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
12000 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12010 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12020 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12030 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
12040 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12050 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
12060 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
12070 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12080 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12090 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
120a0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
120b0 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
120c0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
120d0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
120e0 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
120f0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
12100 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
12110 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12120 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
12130 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
12140 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
12150 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
12160 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
12170 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
12180 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12190 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
121a0 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
121b0 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
121c0 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
121d0 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
121e0 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
121f0 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
12200 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
12210 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
12220 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
12230 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
12240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
12250 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
12260 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12270 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12280 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12290 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
122a0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
122b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
122c0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
122d0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
122e0 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
122f0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
12300 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
12310 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12320 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
12330 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
12340 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
12350 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12360 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
12370 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
12380 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12390 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
123a0 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
123b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
123c0 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
123d0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
123e0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
123f0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
12400 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
12410 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
12420 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
12430 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
12440 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
12450 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
12460 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
12470 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
12480 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
12490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
124a0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
124b0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
124c0 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
124d0 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
124e0 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
124f0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12500 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
12510 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
12520 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
12530 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
12540 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
12550 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
12560 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
12570 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12580 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
12590 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
125a0 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
125b0 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
125c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
125d0 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
125e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
125f0 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
12600 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
12610 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
12620 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12630 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12640 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12650 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12660 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12670 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12680 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
12690 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
126a0 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
126b0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
126c0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
126d0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
126e0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
126f0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
12700 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
12710 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
12720 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
12730 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12740 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12750 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
12760 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12770 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
12780 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
12790 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
127a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
127b0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
127c0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
127d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
127e0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
127f0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12800 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
12810 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
12820 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
12830 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
12840 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12850 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
12860 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
12870 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
12880 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12890 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
128a0 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
128b0 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
128c0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
128d0 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
128e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
128f0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12900 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
12910 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
12920 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
12930 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
12940 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12950 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
12960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12970 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
12980 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
12990 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
129a0 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
129b0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
129c0 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
129d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
129e0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
129f0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12a00 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12a10 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
12a20 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
12a30 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
12a40 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
12a50 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
12a60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12a70 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
12a80 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
12a90 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
12aa0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
12ab0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12ac0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
12ad0 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
12ae0 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
12af0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12b00 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
12b10 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
12b20 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
12b30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12b40 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12b50 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
12b60 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12b70 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
12b80 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12b90 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74  IG_MEMSTATUS opt
12ba0 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
12bb0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
12bc0 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70  e int,.** interp
12bd0 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
12be0 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
12bf0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
12c00 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a  e collection of.
12c10 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
12c20 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e  tion statistics.
12c30 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
12c40 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12c50 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  tics are.** disa
12c60 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
12c70 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
12c80 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
12c90 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
12ca0 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
12cb0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12cc0 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
12cd0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
12ce0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
12cf0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12d00 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
12d10 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
12d20 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
12d30 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  us64()].**   </u
12d40 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
12d50 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12d60 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
12d70 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
12d80 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
12d90 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
12da0 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
12db0 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
12dc0 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
12dd0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
12de0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
12df0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
12e00 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
12e10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12e20 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
12e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12e40 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
12e50 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
12e60 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70  ONFIG_SCRATCH op
12e70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
12e80 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
12e90 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51  uffer.** that SQ
12ea0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
12eb0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
12ec0 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68    ^(There are th
12ed0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ree arguments.**
12ee0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
12ef0 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f  G_SCRATCH:  A po
12f00 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
12f10 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
12f20 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
12f30 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20  ich the scratch 
12f40 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
12f50 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
12f60 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
12f70 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
12f80 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
12f90 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
12fa0 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
12fb0 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a  ocations (N).)^.
12fc0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
12fd0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
12fe0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
12ff0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
13000 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
13010 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
13020 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
13030 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65  ite will not use
13040 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73   more than one s
13050 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
13060 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53  er thread..** ^S
13070 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
13080 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74   request a scrat
13090 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
130a0 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
130b0 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
130c0 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a  ase page size..*
130d0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  * ^If SQLite nee
130e0 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
130f0 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
13100 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
13110 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
13120 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
13130 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
13140 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
13150 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
13160 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
13170 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
13180 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  .<p>.** ^When th
13190 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72  e application pr
131a0 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e  ovides any amoun
131b0 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d  t of scratch mem
131c0 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ory using.** SQL
131d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
131e0 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64  CH, SQLite avoid
131f0 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61  s unnecessary la
13200 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rge.** [sqlite3_
13210 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f  malloc|heap allo
13220 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69  cations]..** Thi
13230 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73  s can help [Robs
13240 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74  on proof|prevent
13250 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13260 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65  on failures] due
13270 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67   to heap.** frag
13280 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77  mentation in low
13290 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64  -memory embedded
132a0 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64   systems..** </d
132b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
132c0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
132d0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
132e0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
132f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13300 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13310 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f  _PAGECACHE optio
13320 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
13330 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
13340 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  er.** that SQLit
13350 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68  e can use for th
13360 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
13370 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
13380 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63  efault page.** c
13390 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
133a0 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
133b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
133c0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
133d0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
133e0 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
133f0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13400 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
13410 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
13420 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13430 5d 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  ].** configurati
13440 6f 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54  on option..** ^T
13450 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13460 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
13470 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13480 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
13490 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
134a0 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
134b0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
134c0 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
134d0 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
134e0 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
134f0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
13500 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
13510 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
13520 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
13530 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
13540 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
13550 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
13560 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
13570 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
13580 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
13590 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
135a0 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
135b0 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
135c0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
135d0 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20  mined using the 
135e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
135f0 43 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74  CACHE_HDRSZ] opt
13600 69 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ion .** to [sqli
13610 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
13620 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73  * ^It is harmles
13630 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
13640 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
13650 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70  .** for the sz p
13660 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c  arameter to be l
13670 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73  arger than neces
13680 73 61 72 79 2e 20 20 54 68 65 20 66 69 72 73 74  sary.  The first
13690 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
136a0 75 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  uld pointer to a
136b0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
136c0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
136d0 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c   that.** is at l
136e0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
136f0 6f 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72  of memory, other
13700 77 69 73 65 20 73 75 62 73 65 71 75 65 6e 74 20  wise subsequent 
13710 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
13720 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51  ndefined..** ^SQ
13730 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
13740 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
13750 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
13760 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
13770 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
13780 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
13790 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
137a0 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
137b0 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
137c0 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
137d0 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
137e0 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
137f0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
13800 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
13810 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
13820 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
13830 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
13840 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
13850 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  space.</dd>.**.*
13860 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13870 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
13880 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
13890 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
138a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
138b0 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
138c0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
138d0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
138e0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
138f0 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
13900 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
13910 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
13920 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
13930 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
13940 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
13950 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
13960 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
13970 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
13980 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
13990 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
139a0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
139b0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
139c0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
139d0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
139e0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
139f0 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
13a00 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
13a10 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
13a20 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
13a30 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
13a40 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
13a50 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
13a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
13a70 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
13a80 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
13a90 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
13aa0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
13ab0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
13ac0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
13ad0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13ae0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
13af0 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
13b00 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
13b10 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
13b20 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
13b30 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
13b40 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
13b50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13b60 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
13b70 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
13b80 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
13b90 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
13ba0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
13bb0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13bc0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
13bd0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
13be0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
13bf0 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
13c00 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
13c10 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
13c20 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
13c30 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
13c40 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
13c50 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
13c60 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13c70 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
13c80 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
13c90 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
13ca0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
13cb0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
13cc0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
13cd0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
13ce0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
13cf0 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
13d00 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
13d10 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
13d20 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
13d30 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
13d40 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
13d50 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
13d60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13d70 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
13d80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13d90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13da0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13db0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
13dc0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13dd0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13de0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
13df0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13e00 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13e10 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13e20 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
13e30 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
13e40 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
13e50 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
13e60 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
13e70 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
13e80 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
13e90 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
13ea0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
13eb0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
13ec0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
13ed0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13ee0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13ef0 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
13f00 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
13f10 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
13f20 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
13f30 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
13f40 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
13f50 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
13f60 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13f70 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
13f80 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
13f90 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
13fa0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
13fb0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
13fc0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
13fd0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
13fe0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13ff0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14000 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
14010 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14020 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
14030 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14040 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14050 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14060 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
14070 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
14080 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
14090 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
140a0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
140b0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
140c0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
140d0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
140e0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
140f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14100 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14110 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
14120 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
14130 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
14140 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
14150 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
14160 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
14170 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
14180 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
14190 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
141a0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
141b0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
141c0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
141d0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
141e0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
141f0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
14200 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
14210 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
14220 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
14230 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
14240 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
14250 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
14260 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14270 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14280 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14290 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
142a0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
142b0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
142c0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
142d0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
142e0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
142f0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
14300 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14310 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
14320 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14330 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14340 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14350 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14360 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14370 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
14380 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14390 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
143a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
143b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
143c0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
143d0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
143e0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
143f0 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
14400 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
14410 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
14420 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
14430 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14440 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
14450 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
14460 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
14470 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
14480 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
14490 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
144a0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
144b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
144c0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
144d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
144e0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
144f0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
14500 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
14510 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
14520 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
14530 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
14540 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
14550 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
14560 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
14570 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
14580 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
14590 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
145a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
145b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
145c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
145d0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
145e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
145f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14600 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14610 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14620 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
14630 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
14640 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14650 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14660 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
14670 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
14680 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
14690 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
146a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
146b0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
146c0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
146d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
146e0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
146f0 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
14700 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14710 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
14720 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14730 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
14740 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14750 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14760 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14770 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14780 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
14790 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
147a0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
147b0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
147c0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
147d0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
147e0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
147f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
14800 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
14810 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
14820 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
14830 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
14840 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
14850 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
14860 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14870 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
14880 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
14890 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
148a0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
148b0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
148c0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
148d0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
148e0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
148f0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
14900 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
14910 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
14920 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
14930 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
14940 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
14950 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
14960 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
14970 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
14980 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
14990 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
149a0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
149b0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
149c0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
149d0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
149e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
149f0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
14a00 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
14a10 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
14a20 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
14a30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14a40 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
14a50 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
14a60 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
14a70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14a80 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
14a90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
14aa0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
14ab0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
14ac0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
14ad0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
14ae0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
14af0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
14b00 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
14b10 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14b20 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
14b30 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
14b40 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
14b50 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
14b60 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
14b70 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
14b80 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
14b90 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
14ba0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
14bb0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
14bc0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
14bd0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
14be0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
14bf0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
14c00 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
14c10 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
14c20 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
14c30 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
14c40 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
14c50 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
14c60 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
14c70 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
14c80 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
14c90 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
14ca0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
14cb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14cc0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14cd0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
14ce0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
14cf0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14d00 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
14d10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14d20 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
14d30 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14d40 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
14d50 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14d60 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
14d70 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
14d80 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
14d90 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
14da0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
14db0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
14dc0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
14dd0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14de0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
14df0 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
14e00 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
14e10 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
14e20 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
14e30 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
14e40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
14e50 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
14e60 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
14e70 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
14e80 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
14e90 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
14ea0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
14eb0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
14ec0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
14ed0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
14ee0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
14ef0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
14f00 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
14f10 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
14f20 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
14f30 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
14f40 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
14f50 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
14f60 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
14f70 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
14f80 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
14f90 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
14fa0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
14fb0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
14fc0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
14fd0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
14fe0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
14ff0 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
15000 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
15010 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
15020 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
15030 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
15040 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
15050 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15060 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15070 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15080 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
15090 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
150a0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
150b0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
150c0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
150d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
150e0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
150f0 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
15100 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
15110 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
15120 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
15130 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
15140 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
15150 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
15160 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
15170 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
15180 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
15190 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
151a0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
151b0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
151c0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
151d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
151e0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
151f0 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
15200 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
15210 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
15220 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
15230 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
15240 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15250 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15260 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
15270 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
15280 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
15290 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
152a0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
152b0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
152c0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
152d0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
152e0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
152f0 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
15300 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
15310 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
15320 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
15330 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
15340 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
15350 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
15360 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
15370 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
15380 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
15390 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
153a0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
153b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
153c0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
153d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
153e0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
153f0 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
15400 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
15410 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
15420 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
15430 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
15440 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
15450 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
15460 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
15470 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
15480 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15490 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
154a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
154b0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
154c0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
154d0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
154e0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
154f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
15500 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
15510 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
15520 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
15530 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15540 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
15550 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15560 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
15570 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
15580 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
15590 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
155a0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
155b0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
155c0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
155d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
155e0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
155f0 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
15600 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
15610 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
15620 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
15630 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15640 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
15650 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15660 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
15670 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15680 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
15690 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
156a0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
156b0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
156c0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
156d0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
156e0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
156f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
15700 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
15710 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
15720 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15730 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
15740 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
15750 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
15760 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
15770 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
15780 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
15790 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
157a0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
157b0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
157c0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
157d0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
157e0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
157f0 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
15800 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15810 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
15820 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
15830 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
15840 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
15850 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
15860 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
15870 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
15880 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
15890 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
158a0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
158b0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
158c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
158d0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
158e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
158f0 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
15900 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
15910 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
15920 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
15930 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
15940 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
15950 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
15960 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
15970 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
15980 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
15990 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
159a0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
159b0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
159c0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
159d0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
159e0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
159f0 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
15a00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15a10 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
15a20 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
15a30 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
15a40 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
15a50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
15a60 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
15a70 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
15a80 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
15a90 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
15aa0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
15ab0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
15ac0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
15ad0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
15ae0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
15af0 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
15b00 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
15b10 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15b20 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
15b30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15b40 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
15b50 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
15b60 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
15b70 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
15b80 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
15b90 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
15ba0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
15bb0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
15bc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15bd0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
15be0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15bf0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15c00 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
15c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15c20 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
15c30 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
15c40 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
15c50 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
15c60 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
15c70 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
15c80 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
15c90 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
15ca0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
15cb0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15cc0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
15cd0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
15ce0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
15cf0 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
15d00 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
15d10 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
15d20 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
15d30 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15d40 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
15d50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15d60 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
15d70 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
15d80 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
15d90 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
15da0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
15db0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
15dc0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15dd0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
15de0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
15df0 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
15e00 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
15e10 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
15e20 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
15e30 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
15e40 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
15e50 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
15e60 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
15e70 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
15e80 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
15e90 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
15ea0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
15eb0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
15ec0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15ed0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
15ee0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
15ef0 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
15f00 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
15f10 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
15f20 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15f30 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
15f40 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
15f50 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
15f60 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
15f70 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
15f80 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
15f90 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
15fa0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
15fb0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
15fc0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
15fd0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
15fe0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
15ff0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16000 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
16010 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
16020 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
16030 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
16040 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
16050 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
16060 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
16070 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
16080 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
16090 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
160a0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
160b0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
160c0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
160d0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
160e0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
160f0 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
16100 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
16110 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  alue..** </dl>.*
16120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16130 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
16140 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
16150 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16160 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
16170 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
16180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16190 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
161a0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
161b0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
161c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
161d0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
161e0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
161f0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16200 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16210 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
16220 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
16230 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
16240 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16250 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
16260 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
16270 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
16280 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16290 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
162a0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
162b0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
162c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
162d0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
162e0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
162f0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
16300 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16310 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
16320 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
16330 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
16340 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16350 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
16360 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
16370 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16380 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16390 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
163a0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
163b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
163c0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
163d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
163e0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
163f0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
16400 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
16410 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16420 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
16430 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
16440 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16450 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
16460 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16470 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16480 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
16490 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
164a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
164b0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
164c0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
164d0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
164e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
164f0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
16500 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
16510 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16520 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
16530 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
16540 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
16550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16560 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
16570 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
16580 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
16590 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
165a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
165b0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
165c0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
165d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
165e0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
165f0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
16600 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
16610 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16620 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
16630 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
16640 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
16650 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16660 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16670 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
16680 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
16690 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
166a0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
166b0 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
166c0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
166d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
166e0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
166f0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
16700 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
16710 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ma */../*.** CAP
16720 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
16730 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
16740 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
16750 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
16760 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
16770 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
16780 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16790 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
167a0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
167b0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
167c0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
167d0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
167e0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
167f0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
16800 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
16810 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
16820 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
16830 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
16840 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
16850 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
16860 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
16870 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
16880 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
16890 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
168a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
168b0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
168c0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
168d0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
168e0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
168f0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
16900 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
16910 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
16920 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
16930 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
16940 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
16950 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16960 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
16970 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
16980 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
16990 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
169a0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
169b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
169c0 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
169d0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
169e0 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
169f0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
16a00 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
16a10 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
16a20 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
16a30 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
16a40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16a50 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
16a60 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
16a70 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
16a80 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
16a90 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
16aa0 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
16ab0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
16ac0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
16ad0 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
16ae0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
16af0 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
16b00 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
16b10 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
16b20 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
16b30 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
16b40 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
16b50 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
16b60 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
16b70 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
16b80 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
16b90 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
16ba0 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
16bb0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
16bc0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
16bd0 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
16be0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
16bf0 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
16c00 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
16c10 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
16c20 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
16c30 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
16c40 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
16c50 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
16c60 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
16c70 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
16c80 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
16c90 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
16ca0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
16cb0 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
16cc0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
16cd0 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
16ce0 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
16cf0 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
16d00 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
16d10 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
16d20 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
16d30 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
16d40 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
16d50 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
16d60 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
16d70 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
16d80 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
16d90 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
16da0 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
16db0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
16dc0 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
16dd0 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
16de0 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
16df0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
16e00 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
16e10 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
16e20 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
16e30 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
16e40 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
16e50 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
16e60 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
16e70 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
16e80 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
16e90 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
16ea0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
16eb0 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
16ec0 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
16ed0 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
16ee0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
16ef0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16f00 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
16f10 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
16f20 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
16f30 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
16f40 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
16f50 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
16f60 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
16f70 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
16f80 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
16f90 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
16fa0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16fb0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
16fc0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
16fd0 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
16fe0 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
16ff0 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
17000 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
17010 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
17020 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
17030 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
17040 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17050 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
17060 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
17070 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
17080 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
17090 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
170a0 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
170b0 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
170c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
170d0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
170e0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
170f0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
17100 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
17110 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
17120 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
17130 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
17140 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
17150 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17160 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
17170 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
17180 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
17190 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
171a0 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
171b0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
171c0 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
171d0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
171e0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
171f0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
17200 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17210 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
17220 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
17230 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
17240 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
17250 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
17260 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
17270 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
17280 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
17290 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
172a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
172b0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
172c0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
172d0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
172e0 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
172f0 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
17300 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
17310 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
17320 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
17330 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
17340 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17350 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17360 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
17370 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
17380 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
17390 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
173a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
173b0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
173c0 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f  DE       1001  /
173d0 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
173e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
173f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17400 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20  E_FKEY     1002 
17410 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
17420 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17430 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
17440 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a  RIGGER  1003  /*
17450 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
17460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
17470 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
17480 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
17490 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44   Codes.** METHOD
174a0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
174b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
174c0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
174d0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
174e0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
174f0 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
17500 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
17510 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
17520 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
17530 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
17540 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
17550 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
17560 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
17570 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ility..*/.SQLITE
17580 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
17590 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
175a0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
175b0 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
175c0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
175d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
175e0 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
175f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
17600 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  3.**.** ^Each en
17610 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69  try in most SQLi
17620 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70  te tables (excep
17630 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52  t for [WITHOUT R
17640 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a  OWID] tables).**
17650 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
17660 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
17670 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
17680 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
17690 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
176a0 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
176b0 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
176c0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
176d0 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
176e0 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
176f0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
17700 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
17710 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
17720 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
17730 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
17740 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
17750 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
17760 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
17770 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
17780 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
17790 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
177a0 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
177b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
177c0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
177d0 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (D) interface re
177e0 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
177f0 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73  ] of the .** mos
17800 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
17810 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
17820 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
17830 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
17840 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
17850 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
17860 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f  ** ^Inserts into
17870 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
17880 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20   tables are not 
17890 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66  recorded..** ^If
178a0 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
178b0 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f  INSERT]s into ro
178c0 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61  wid tables.** ha
178d0 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
178e0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
178f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a   connection D, .
17900 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
17910 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17920 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72  d(D) returns zer
17930 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  o..**.** ^(If an
17940 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
17950 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
17960 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
17970 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
17980 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
17990 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
179a0 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
179b0 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
179c0 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
179d0 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
179e0 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
179f0 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
17a00 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
17a10 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
17a20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
17a30 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
17a40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
17a50 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
17a60 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
17a70 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
17a80 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
17a90 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
17aa0 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
17ab0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
17ac0 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
17ad0 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
17ae0 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
17af0 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
17b00 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
17b10 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
17b20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17b30 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
17b40 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
17b50 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
17b60 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
17b70 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
17b80 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
17b90 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
17ba0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
17bb0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
17bc0 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
17bd0 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
17be0 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
17bf0 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
17c00 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
17c10 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
17c20 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
17c30 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
17c40 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
17c50 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
17c60 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
17c70 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
17c80 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
17c90 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
17ca0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
17cb0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
17cc0 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
17cd0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
17ce0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
17cf0 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
17d00 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
17d10 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
17d20 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
17d30 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
17d40 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
17d50 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
17d60 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
17d70 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
17d80 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
17d90 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
17da0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
17db0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
17dc0 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
17dd0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
17de0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
17df0 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
17e00 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
17e10 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
17e20 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
17e30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
17e40 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
17e50 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
17e60 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
17e70 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
17e80 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
17e90 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
17ea0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
17eb0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
17ec0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
17ed0 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
17ee0 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
17ef0 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
17f00 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
17f10 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
17f20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49  [rowid]..*/.SQLI
17f30 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
17f40 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43  nt64 SQLITE_STDC
17f50 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  ALL sqlite3_last
17f60 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
17f70 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
17f80 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
17f90 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
17fa0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
17fb0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
17fc0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
17fd0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
17fe0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
17ff0 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65  odified, inserte
18000 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d or.** deleted 
18010 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
18020 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
18030 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
18040 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
18050 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61  ment on the data
18060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18070 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
18080 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e   only parameter.
18090 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61  .** ^Executing a
180a0 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
180b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
180c0 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  oes not modify t
180d0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
180e0 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
180f0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ction..**.** ^On
18100 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
18110 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  directly by the 
18120 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
18130 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
18140 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64  nt are.** consid
18150 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79  ered - auxiliary
18160 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
18170 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  by [CREATE TRIGG
18180 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20  ER | triggers], 
18190 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
181a0 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45   actions] or [RE
181b0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
181c0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
181d0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
181e0 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20   .** Changes to 
181f0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
18200 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a  intercepted by .
18210 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  ** [INSTEAD OF t
18220 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44  rigger | INSTEAD
18230 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72   OF triggers] ar
18240 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e  e not counted. ^
18250 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65  The value .** re
18260 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
18270 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65  3_changes() imme
18280 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e  diately after an
18290 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
182a0 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74  or .** DELETE st
182b0 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61  atement run on a
182c0 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20   view is always 
182d0 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67  zero. Only chang
182e0 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20  es made to real 
182f0 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63  .** tables are c
18300 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  ounted..**.** Th
18310 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f  ings are more co
18320 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65  mplicated if the
18330 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18340 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  () function is.*
18350 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65  * executed while
18360 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
18370 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54  am is running. T
18380 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69  his may happen i
18390 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  f the.** program
183a0 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67   uses the [chang
183b0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
183c0 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f  n], or if some o
183d0 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ther callback.**
183e0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65   function invoke
183f0 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  s sqlite3_change
18400 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73  s() directly. Es
18410 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a  sentially:.** .*
18420 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
18430 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69   ^(Before enteri
18440 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  ng a trigger pro
18450 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72  gram the value r
18460 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20  eturned by.**   
18470 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61       sqlite3_cha
18480 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
18490 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20  is saved. After 
184a0 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67  the trigger prog
184b0 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68  ram .**        h
184c0 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65  as finished, the
184d0 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20   original value 
184e0 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a  is restored.)^.*
184f0 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57  * .**   <li> ^(W
18500 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
18510 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53  program each INS
18520 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20  ERT, UPDATE and 
18530 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20  DELETE .**      
18540 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73    statement sets
18550 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18560 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
18570 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
18580 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74      upon complet
18590 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f  ion as normal. O
185a0 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76  f course, this v
185b0 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e  alue will not in
185c0 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20  clude .**       
185d0 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72   any changes per
185e0 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72  formed by sub-tr
185f0 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73  iggers, as the s
18600 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
18610 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75   .**        valu
18620 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20  e will be saved 
18630 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74  and restored aft
18640 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67  er each sub-trig
18650 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a  ger has run.)^.*
18660 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e  * </ul>.** .** ^
18670 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
18680 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29  if the changes()
18690 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f   SQL function (o
186a0 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73  r similar) is us
186b0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
186c0 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  st INSERT, UPDAT
186d0 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
186e0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
186f0 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72  rigger, it .** r
18700 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
18710 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   as set when the
18720 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65   calling stateme
18730 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69  nt began executi
18740 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ng..** ^If it is
18750 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63   used by the sec
18760 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ond or subsequen
18770 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74  t such statement
18780 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
18790 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74  r .** program, t
187a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
187b0 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e  d reflects the n
187c0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
187d0 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  dified by the .*
187e0 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52  * previous INSER
187f0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
18800 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
18810 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72  thin the same tr
18820 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  igger..**.** See
18830 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
18840 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
18850 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
18860 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
18870 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
18880 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
18890 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
188a0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
188b0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
188c0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
188d0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
188e0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
188f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
18900 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
18910 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
18920 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
18930 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
18940 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
18950 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
18960 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
18970 4c 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  L sqlite3_change
18980 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
18990 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
189a0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
189b0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
189c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
189d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
189e0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
189f0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
18a00 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d  rows inserted, m
18a10 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65  odified or.** de
18a20 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e  leted by all [IN
18a30 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20  SERT], [UPDATE] 
18a40 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
18a50 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64  ements completed
18a60 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61  .** since the da
18a70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18a80 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e  n was opened, in
18a90 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78  cluding those ex
18aa0 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72  ecuted as.** par
18ab0 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
18ac0 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e  grams. ^Executin
18ad0 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
18ae0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
18af0 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66  t.** does not af
18b00 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72  fect the value r
18b10 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
18b20 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
18b30 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e  ()..** .** ^Chan
18b40 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74  ges made as part
18b50 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   of [foreign key
18b60 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e   actions] are in
18b70 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a  cluded in the.**
18b80 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73   count, but thos
18b90 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  e made as part o
18ba0 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
18bb0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
18bc0 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61  are.** not. ^Cha
18bd0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
18be0 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
18bf0 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f  ted by INSTEAD O
18c00 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61  F triggers .** a
18c10 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
18c20 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  ** .** See also 
18c30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
18c40 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
18c50 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
18c60 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
18c70 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
18c80 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
18c90 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
18ca0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
18cb0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
18cc0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
18cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18ce0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
18cf0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
18d00 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
18d10 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
18d20 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
18d30 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
18d40 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
18d50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
18d60 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
18d70 4c 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  L sqlite3_total_
18d80 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
18d90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18da0 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
18db0 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
18dc0 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ry.** METHOD: sq
18dd0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
18de0 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
18df0 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
18e00 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
18e10 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
18e20 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
18e30 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
18e40 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
18e50 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
18e60 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
18e70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
18e80 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
18e90 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
18ea0 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
18eb0 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
18ec0 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
18ed0 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
18ee0 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
18ef0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
18f00 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
18f10 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
18f20 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
18f30 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
18f40 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
18f50 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
18f60 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
18f70 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
18f80 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
18f90 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
18fa0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
18fb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
18fc0 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
18fd0 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
18fe0 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
18ff0 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
19000 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
19010 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
19020 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
19030 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
19040 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
19050 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
19060 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
19070 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
19080 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
19090 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
190a0 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
190b0 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
190c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
190d0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
190e0 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
190f0 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
19100 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
19110 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
19120 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
19130 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
19140 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
19150 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
19160 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
19170 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
19180 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
19190 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
191a0 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
191b0 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
191c0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
191d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
191e0 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
191f0 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
19200 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
19210 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
19220 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
19230 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
19240 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
19250 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
19260 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
19270 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
19280 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19290 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
192a0 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
192b0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
192c0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
192d0 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
192e0 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
192f0 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
19300 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
19310 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
19320 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
19330 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
19340 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
19350 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
19360 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
19370 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
19380 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
19390 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
193a0 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
193b0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
193c0 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
193d0 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
193e0 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
193f0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
19400 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
19410 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
19420 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
19430 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
19440 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
19450 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
19460 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
19470 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ns..**.** If the
19480 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19490 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
194a0 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
194b0 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75  rupt()].** is ru
194c0 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
194d0 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
194e0 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  y happen..*/.SQL
194f0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
19500 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
19510 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
19520 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19530 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
19540 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
19550 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
19560 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
19570 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
19580 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
19590 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
195a0 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
195b0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
195c0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
195d0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
195e0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
195f0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
19600 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
19610 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
19620 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
19630 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
19640 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
19650 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
19660 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
19670 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
19680 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
19690 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
196a0 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
196b0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
196c0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
196d0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
196e0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
196f0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
19700 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
19710 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
19720 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
19730 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
19740 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
19750 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
19760 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
19770 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
19780 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
19790 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
197a0 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
197b0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
197c0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
197d0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
197e0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
197f0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
19800 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
19810 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
19820 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
19830 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
19840 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
19850 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
19860 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
19870 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
19880 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
19890 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
198a0 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
198b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
198c0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
198d0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
198e0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
198f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
19900 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
19910 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
19920 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
19930 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
19940 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
19950 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
19960 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
19970 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
19980 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
19990 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
199a0 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
199b0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
199c0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
199d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
199e0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
199f0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
19a00 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19a10 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
19a20 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
19a30 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
19a40 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
19a50 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19a60 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
19a70 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
19a80 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
19a90 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
19aa0 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
19ab0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
19ac0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
19ad0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
19ae0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
19af0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
19b00 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
19b10 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
19b20 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
19b30 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
19b40 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
19b50 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
19b60 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
19b70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
19b80 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
19b90 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  LL sqlite3_compl
19ba0 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
19bb0 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  sql);.SQLITE_API
19bc0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
19bd0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ALL sqlite3_comp
19be0 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
19bf0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
19c00 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
19c10 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
19c20 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
19c30 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45  USY Errors.** KE
19c40 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61  YWORDS: {busy-ha
19c50 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20  ndler callback} 
19c60 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a  {busy handler}.*
19c70 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19c80 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
19c90 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19ca0 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65  r(D,X,P) routine
19cb0 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
19cc0 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74   function X.** t
19cd0 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
19ce0 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
19cf0 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
19d00 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
19d10 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20  ade to access a 
19d20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
19d30 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
19d40 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
19d50 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61  ection] D when a
19d60 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
19d70 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
19d80 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64  the table locked
19d90 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
19da0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20  _busy_handler() 
19db0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
19dc0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a  d to implement.*
19dd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
19de0 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b  timeout()] and [
19df0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
19e00 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  out]..**.** ^If 
19e10 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
19e20 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
19e30 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
19e40 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
19e50 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
19e60 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
19e70 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
19e80 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
19e90 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
19ea0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
19eb0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
19ec0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
19ed0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
19ee0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
19ef0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19f00 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
19f10 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
19f20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
19f30 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
19f40 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
19f50 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
19f60 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
19f70 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
19f80 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
19f90 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
19fa0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
19fb0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
19fc0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
19fd0 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20   previously for 
19fe0 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
19ff0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
1a000 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
1a010 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
1a020 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
1a030 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
1a040 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
1a050 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1a060 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73  [SQLITE_BUSY] is
1a070 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20   returned.** to 
1a080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1a090 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
1a0a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1a0b0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
1a0c0 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
1a0d0 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1a0e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1a0f0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
1a100 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
1a110 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
1a120 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
1a130 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
1a140 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
1a150 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
1a160 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
1a170 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
1a180 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
1a190 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
1a1a0 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
1a1b0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
1a1c0 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
1a1d0 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
1a1e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
1a1f0 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61  USY].** to the a
1a200 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65  pplication inste
1a210 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
1a220 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  he .** busy hand
1a230 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
1a240 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
1a250 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
1a260 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
1a270 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
1a280 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
1a290 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
1a2a0 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
1a2b0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1a2c0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
1a2d0 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
1a2e0 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
1a2f0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
1a300 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
1a310 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
1a320 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
1a330 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
1a340 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1a350 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
1a360 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1a370 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
1a380 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
1a390 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1a3a0 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
1a3b0 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
1a3c0 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
1a3d0 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
1a3e0 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
1a3f0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
1a400 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
1a410 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
1a420 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
1a430 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
1a440 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
1a450 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
1a460 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
1a470 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
1a480 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
1a490 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
1a4a0 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
1a4b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
1a4c0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
1a4d0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
1a4e0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1a4f0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1a500 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
1a510 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
1a520 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a530 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
1a540 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
1a550 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
1a560 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
1a570 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
1a580 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
1a590 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1a5a0 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61  out()].** or eva
1a5b0 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20  luating [PRAGMA 
1a5c0 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20  busy_timeout=N] 
1a5d0 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a  will change the.
1a5e0 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ** busy handler 
1a5f0 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61  and thus clear a
1a600 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ny previously se
1a610 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  t busy handler..
1a620 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
1a630 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
1a640 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
1a650 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
1a660 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1a670 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1a680 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1a690 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f  y handler.  In o
1a6a0 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74  ther words,.** t
1a6b0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1a6c0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
1a6d0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
1a6e0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
1a6f0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
1a700 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
1a710 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
1a720 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
1a730 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a740 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
1a750 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1a760 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1a770 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53  sy handler..*/.S
1a780 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
1a790 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1a7a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a7b0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
1a7c0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
1a7d0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1a7e0 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1a7f0 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45  sy Timeout.** ME
1a800 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1a810 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1a820 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1a830 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1a840 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1a850 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1a860 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1a870 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1a880 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1a890 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1a8a0 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1a8b0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1a8c0 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1a8d0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1a8e0 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1a8f0 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1a900 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1a910 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1a920 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1a930 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1a940 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1a950 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1a960 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1a970 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1a980 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1a990 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1a9a0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1a9b0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1a9c0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1a9d0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1a9e0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1a9f0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1aa00 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1aa10 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1aa20 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1aa30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1aa40 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1aa50 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1aa60 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1aa70 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1aa80 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1aa90 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1aaa0 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1aab0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1aac0 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1aad0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1aae0 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1aaf0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1ab00 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1ab10 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  out].*/.SQLITE_A
1ab20 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
1ab30 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75  DCALL sqlite3_bu
1ab40 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
1ab50 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
1ab60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1ab70 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
1ab80 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
1ab90 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f  Queries.** METHO
1aba0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1abb0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1abc0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1abd0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1abe0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1abf0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1ac00 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1ac10 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1ac20 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1ac30 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1ac40 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1ac50 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1ac60 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1ac70 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1ac80 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1ac90 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1aca0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1acb0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1acc0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1acd0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1ace0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1acf0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1ad00 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1ad10 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1ad20 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1ad30 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1ad40 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1ad50 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1ad60 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1ad70 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1ad80 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1ad90 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1ada0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1adb0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1adc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1add0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1ade0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1adf0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1ae00 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1ae10 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1ae20 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1ae30 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1ae40 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1ae50 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1ae60 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1ae70 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1ae80 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1ae90 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1aea0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1aeb0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1aec0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1aed0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1aee0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1aef0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1af00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1af10 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1af20 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1af30 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1af40 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1af50 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1af60 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1af70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1af80 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1af90 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1afa0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1afb0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1afc0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1afd0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1afe0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1aff0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1b000 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b010 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1b020 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1b030 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1b040 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1b050 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1b060 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1b070 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1b080 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1b090 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1b0a0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1b0b0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b0c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b0d0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1b0e0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1b0f0 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1b100 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1b110 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1b120 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1b130 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1b140 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1b150 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1b160 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b170 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1b180 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1b190 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1b1a0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1b1b0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1b1c0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1b1d0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1b1e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1b1f0 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1b200 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1b210 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1b220 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1b230 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1b240 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b250 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1b260 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1b270 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1b280 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1b290 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1b2a0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b2b0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1b2c0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b2d0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1b2e0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b2f0 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1b300 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b310 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1b320 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1b330 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1b340 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1b350 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b360 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1b370 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b380 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1b390 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b3a0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1b3b0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1b3c0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1b3d0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1b3e0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1b3f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1b400 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1b410 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1b420 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1b430 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1b440 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1b450 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1b460 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1b470 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1b480 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1b490 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1b4a0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1b4b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1b4c0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1b4d0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1b4e0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1b4f0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1b500 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1b510 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1b520 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1b530 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1b540 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1b550 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1b560 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1b570 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1b580 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1b590 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1b5a0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1b5b0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1b5c0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1b5d0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1b5e0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1b5f0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1b600 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1b610 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1b620 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1b630 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b640 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1b650 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1b660 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1b670 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1b680 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1b690 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1b6a0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1b6b0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1b6c0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1b6d0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1b6e0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1b6f0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1b700 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1b710 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1b720 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1b730 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1b740 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1b750 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1b760 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1b770 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1b780 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1b790 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1b7a0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1b7b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1b7c0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1b7d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1b7e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1b7f0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
1b800 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  L sqlite3_get_ta
1b810 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1b820 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1b830 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1b840 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1b850 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1b860 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1b870 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1b880 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1b890 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1b8a0 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1b8b0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1b8c0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1b8d0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1b8e0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1b8f0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1b900 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1b910 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1b920 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1b930 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1b940 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1b950 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1b960 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
1b970 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44   void SQLITE_STD
1b980 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65  CALL sqlite3_fre
1b990 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1b9a0 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1b9b0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1b9c0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1b9d0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1b9e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b9f0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1ba00 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1ba10 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1ba20 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1ba30 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1ba40 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65  ibrary..** These
1ba50 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73   routines unders
1ba60 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65  tand most of the
1ba70 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d   common K&R form
1ba80 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a  atting options,.
1ba90 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64  ** plus some add
1baa0 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e  itional non-stan
1bab0 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65  dard formats, de
1bac0 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a  tailed below..**
1bad0 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20   Note that some 
1bae0 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63  of the more obsc
1baf0 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  ure formatting o
1bb00 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65  ptions from rece
1bb10 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20  nt.** C-library 
1bb20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d  standards are om
1bb30 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20  itted from this 
1bb40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
1bb50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1bb60 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
1bb70 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1bb80 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
1bb90 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
1bba0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
1bbb0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
1bbc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1bbd0 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
1bbe0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1bbf0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
1bc00 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
1bc10 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
1bc20 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
1bc30 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
1bc40 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1bc50 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
1bc60 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
1bc70 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1bc80 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
1bc90 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
1bca0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
1bcb0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1bcc0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
1bcd0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
1bce0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
1bcf0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1bd00 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1bd10 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
1bd20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1bd30 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
1bd40 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
1bd50 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
1bd60 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
1bd70 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
1bd80 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
1bd90 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
1bda0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
1bdb0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
1bdc0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
1bdd0 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
1bde0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
1bdf0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
1be00 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
1be10 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
1be20 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
1be30 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1be40 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
1be50 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
1be60 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
1be70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
1be80 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
1be90 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
1bea0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
1beb0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
1bec0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
1bed0 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
1bee0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
1bef0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
1bf00 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
1bf10 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
1bf20 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
1bf30 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
1bf40 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
1bf50 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
1bf60 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1bf70 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
1bf80 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
1bf90 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
1bfa0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
1bfb0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
1bfc0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
1bfd0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1bfe0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
1bff0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
1c000 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
1c010 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
1c020 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1c030 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
1c040 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
1c050 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
1c060 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
1c070 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1c080 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
1c090 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
1c0a0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
1c0b0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
1c0c0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
1c0d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1c0e0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1c0f0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
1c100 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
1c110 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1c120 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
1c130 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
1c140 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
1c150 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
1c160 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
1c170 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
1c180 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
1c190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1c1a0 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
1c1b0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
1c1c0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1c1d0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
1c1e0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
1c1f0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
1c200 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f   "%w" and "%z" o
1c210 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
1c220 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
1c230 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
1c240 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
1c250 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  es a nul-termina
1c260 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
1c270 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
1c280 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
1c290 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
1c2a0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
1c2b0 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
1c2c0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
1c2d0 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
1c2e0 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
1c2f0 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
1c300 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
1c310 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
1c320 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
1c330 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
1c340 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
1c350 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
1c360 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
1c370 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
1c380 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
1c390 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
1c3a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1c3b0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1c3c0 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
1c3d0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
1c3e0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1c3f0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
1c400 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
1c410 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
1c420 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
1c430 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1c440 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c450 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1c460 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1c470 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1c480 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
1c490 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1c4a0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1c4b0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1c4c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1c4d0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1c4e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c4f0 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
1c500 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
1c510 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
1c520 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
1c530 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
1c540 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
1c550 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
1c560 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1c570 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c580 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1c590 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1c5a0 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
1c5b0 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
1c5c0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c5d0 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
1c5e0 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
1c5f0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
1c600 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
1c610 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
1c620 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
1c630 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1c640 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1c650 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1c660 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
1c670 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
1c680 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c690 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1c6a0 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
1c6b0 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
1c6c0 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
1c6d0 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
1c6e0 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
1c6f0 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
1c700 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
1c710 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
1c720 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
1c730 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
1c740 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1c750 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
1c760 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
1c770 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
1c780 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
1c790 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
1c7a0 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
1c7b0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1c7c0 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
1c7d0 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
1c7e0 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
1c7f0 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
1c800 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
1c810 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
1c820 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
1c830 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
1c840 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
1c850 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c860 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1c870 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1c880 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1c890 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
1c8a0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1c8b0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1c8c0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1c8d0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1c8e0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1c8f0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1c900 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
1c910 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
1c920 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
1c930 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
1c940 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
1c950 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
1c960 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
1c970 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1c980 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f  ** ^(The "%w" fo
1c990 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1c9a0 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63  is like "%q" exc
1c9b0 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65  ept that it expe
1c9c0 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e  cts to.** be con
1c9d0 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f  tained within do
1c9e0 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74  uble-quotes inst
1c9f0 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75  ead of single qu
1ca00 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20  otes, and it.** 
1ca10 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62  escapes the doub
1ca20 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74  le-quote charact
1ca30 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1ca40 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a  e single-quote.*
1ca50 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20  * character.)^  
1ca60 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1ca70 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ing option is in
1ca80 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c  tended for safel
1ca90 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74  y inserting.** t
1caa0 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
1cab0 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e  names into a con
1cac0 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61  structed SQL sta
1cad0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tement..**.** ^(
1cae0 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
1caf0 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
1cb00 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
1cb10 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
1cb20 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
1cb30 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
1cb40 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
1cb50 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
1cb60 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
1cb70 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
1cb80 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
1cb90 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49  tring.)^.*/.SQLI
1cba0 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c  TE_API char *SQL
1cbb0 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65  ITE_CDECL sqlite
1cbc0 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1cbd0 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49  char*,...);.SQLI
1cbe0 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c  TE_API char *SQL
1cbf0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1cc00 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1cc10 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1cc20 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
1cc30 68 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43  har *SQLITE_CDEC
1cc40 4c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  L sqlite3_snprin
1cc50 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1cc60 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1cc70 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1cc80 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
1cc90 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1cca0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1ccb0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1ccc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ccd0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1cce0 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
1ccf0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
1cd00 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
1cd10 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
1cd20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
1cd30 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
1cd40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1cd50 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
1cd60 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
1cd70 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
1cd80 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
1cd90 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
1cda0 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
1cdb0 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
1cdc0 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
1cdd0 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
1cde0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
1cdf0 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
1ce00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1ce10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1ce20 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1ce30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
1ce40 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
1ce50 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1ce60 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
1ce70 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
1ce80 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
1ce90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1cea0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
1ceb0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
1cec0 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
1ced0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1cee0 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
1cef0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
1cf00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1cf10 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
1cf20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
1cf30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1cf40 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
1cf50 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1cf60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1cf70 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65  loc64(N) routine
1cf80 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65   works just like
1cf90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1cfa0 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 61  oc(N) except tha
1cfb0 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  t N is an unsign
1cfc0 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  ed 64-bit intege
1cfd0 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1cfe0 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20  a signed 32-bit 
1cff0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1d000 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
1d010 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
1d020 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
1d030 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1d040 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d050 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1d060 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
1d070 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
1d080 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
1d090 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
1d0a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
1d0b0 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
1d0c0 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
1d0d0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1d0e0 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
1d0f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1d100 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
1d110 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
1d120 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
1d130 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
1d140 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
1d150 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
1d160 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
1d170 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
1d180 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
1d190 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
1d1a0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1d1b0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1d1c0 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
1d1d0 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
1d1e0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1d1f0 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
1d200 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
1d210 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
1d220 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
1d230 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
1d240 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
1d250 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
1d260 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1d270 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1d280 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d290 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
1d2a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d2b0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  N) interface att
1d2c0 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
1d2d0 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
1d2e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74  y allocation X t
1d2f0 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
1d300 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
1d310 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e X parameter to
1d320 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d330 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55  (X,N).** is a NU
1d340 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1d350 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
1d360 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
1d370 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1d380 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49  malloc(N)..** ^I
1d390 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  f the N paramete
1d3a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1d3b0 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72  lloc(X,N) is zer
1d3c0 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
1d3d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1d3e0 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
1d3f0 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
1d400 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
1d410 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  e(X)..** ^sqlite
1d420 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1d430 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1d440 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1d450 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1d460 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1d470 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1d480 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d  f insufficient m
1d490 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62  emory is availab
1d4a0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1d4b0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1d4c0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1d4d0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1d4e0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1d4f0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1d500 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1d510 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1d520 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1d530 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1d540 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64  realloc(X,N) and
1d550 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1d560 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
1d570 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
1d580 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1d590 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69  rns NULL and N i
1d5a0 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
1d5b0 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c   the.** prior al
1d5c0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  location is not 
1d5d0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
1d5e0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1d5f0 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  c64(X,N) interfa
1d600 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61  ces works the sa
1d610 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33  me as.** sqlite3
1d620 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78  _realloc(X,N) ex
1d630 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61  cept that N is a
1d640 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
1d650 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1d660 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20  .** of a 32-bit 
1d670 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a  signed integer..
1d680 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61  **.** ^If X is a
1d690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1d6a0 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  on previously ob
1d6b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1d6c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  te3_malloc(),.**
1d6d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1d6e0 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  4(), sqlite3_rea
1d6f0 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74  lloc(), or sqlit
1d700 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20  e3_realloc64(), 
1d710 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
1d720 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73  msize(X) returns
1d730 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61   the size of tha
1d740 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
1d750 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a  ion in bytes..**
1d760 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1d770 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1d780 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62  msize(X) might b
1d790 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
1d7a0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62  e number.** of b
1d7b0 79 74 65 73 20 72 65 71 75 65 73 74 65 64 20 77  ytes requested w
1d7c0 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61  hen X was alloca
1d7d0 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61  ted.  ^If X is a
1d7e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1d7f0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1d800 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a  ize(X) returns z
1d810 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74  ero.  If X point
1d820 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74  s to something t
1d830 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68  hat is not.** th
1d840 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d  e beginning of m
1d850 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d860 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74  , or if it point
1d870 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a  s to a formerly.
1d880 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20  ** valid memory 
1d890 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20  allocation that 
1d8a0 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65  has now been fre
1d8b0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
1d8c0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69  avior.** of sqli
1d8d0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20  te3_msize(X) is 
1d8e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f  undefined and po
1d8f0 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  ssibly harmful..
1d900 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1d910 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
1d920 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20  lite3_malloc(), 
1d930 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d940 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
1d950 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71  lloc64(), and sq
1d960 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1d970 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
1d980 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
1d990 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
1d9a0 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a  ndary, or to a.*
1d9b0 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72  * 4 byte boundar
1d9c0 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  y if the [SQLITE
1d9d0 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f  _4_BYTE_ALIGNED_
1d9e0 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d  MALLOC] compile-
1d9f0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  time.** option i
1da00 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  s used..**.** In
1da10 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1da20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
1da30 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
1da40 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
1da50 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
1da60 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
1da70 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
1da80 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
1da90 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1daa0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1dab0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
1dac0 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
1dad0 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
1dae0 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
1daf0 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
1db00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
1db10 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
1db20 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
1db30 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c   version 3.7.10,
1db40 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   the Windows OS 
1db50 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
1db60 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79  called.** the sy
1db70 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
1db80 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
1db90 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
1dba0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
1dbb0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
1dbc0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
1dbd0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
1dbe0 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
1dbf0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
1dc00 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
1dc10 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
1dc20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
1dc30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1dc40 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74   errors were det
1dc50 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
1dc60 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64  ey were reported
1dc70 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
1dc80 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
1dc90 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
1dca0 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
1dcb0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
1dcc0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
1dcd0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
1dce0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
1dcf0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1dd00 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
1dd10 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
1dd20 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
1dd30 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
1dd40 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
1dd50 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1dd60 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
1dd70 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
1dd80 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
1dd90 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
1dda0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
1ddb0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
1ddc0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
1ddd0 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
1dde0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
1ddf0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
1de00 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
1de10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1de20 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1de30 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53  realloc()]..*/.S
1de40 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1de50 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1de60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
1de70 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
1de80 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
1de90 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ALL sqlite3_mall
1dea0 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
1deb0 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
1dec0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
1ded0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65  DCALL sqlite3_re
1dee0 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1def0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1df00 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
1df10 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  LL sqlite3_reall
1df20 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69  oc64(void*, sqli
1df30 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c  te3_uint64);.SQL
1df40 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
1df50 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1df60 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
1df70 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
1df80 74 65 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 54  te3_uint64 SQLIT
1df90 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1dfa0 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a  3_msize(void*);.
1dfb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1dfc0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
1dfd0 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
1dfe0 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
1dff0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
1e000 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
1e010 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
1e020 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
1e030 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1e040 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1e050 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1e060 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
1e070 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
1e080 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
1e090 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1e0a0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
1e0b0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1e0c0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1e0d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1e0e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1e0f0 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
1e100 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
1e110 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
1e120 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
1e130 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
1e140 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e150 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
1e160 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
1e170 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
1e180 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1e190 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
1e1a0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1e1b0 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
1e1c0 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
1e1d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1e1e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1e1f0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1e200 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1e210 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
1e220 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
1e230 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
1e240 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
1e250 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
1e260 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
1e270 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
1e280 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
1e290 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
1e2a0 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
1e2b0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
1e2c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1e2d0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
1e2e0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
1e2f0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
1e300 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
1e310 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
1e320 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e330 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
1e340 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
1e350 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
1e360 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1e370 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
1e380 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
1e390 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
1e3a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e3b0 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
1e3c0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1e3d0 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
1e3e0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49  e reset..*/.SQLI
1e3f0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
1e400 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43  nt64 SQLITE_STDC
1e410 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ALL sqlite3_memo
1e420 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53  ry_used(void);.S
1e430 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1e440 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53  3_int64 SQLITE_S
1e450 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d  TDCALL sqlite3_m
1e460 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1e470 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
1e480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e490 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
1e4a0 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a  umber Generator.
1e4b0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
1e4c0 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
1e4d0 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
1e4e0 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
1e4f0 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
1e500 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
1e510 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57  dom [ROWID | ROW
1e520 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74  IDs] when insert
1e530 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
1e540 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
1e550 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
1e560 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
1e570 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20  ssible [ROWID]. 
1e580 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
1e590 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
1e5a0 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
1e5b0 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
1e5c0 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
1e5d0 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
1e5e0 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
1e5f0 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
1e600 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
1e610 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
1e620 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  poses..**.** ^A 
1e630 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1e640 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
1e650 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
1e660 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
1e670 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d  .** ^The P param
1e680 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55  eter can be a NU
1e690 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1e6a0 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69  * ^If this routi
1e6b0 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  ne has not been 
1e6c0 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65  previously calle
1e6d0 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76  d or if the prev
1e6e0 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64  ious.** call had
1e6f0 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65   N less than one
1e700 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
1e710 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74  er for P, then t
1e720 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65  he PRNG is.** se
1e730 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
1e740 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66  mness obtained f
1e750 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
1e760 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a  ess method of.**
1e770 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1e780 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1e790 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  t..** ^If the pr
1e7a0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
1e7b0 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20  his routine had 
1e7c0 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72  an N of 1 or mor
1e7d0 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e  e and a.** non-N
1e7e0 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70  ULL P then the p
1e7f0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
1e800 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
1e810 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
1e820 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
1e830 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1e840 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
1e850 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
1e860 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1e870 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1e880 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1e890 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1e8a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e8b0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1e8c0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1e8d0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
1e8e0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1e8f0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1e900 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
1e910 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e920 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
1e930 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1e940 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
1e950 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
1e960 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
1e970 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1e980 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1e990 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
1e9a0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
1e9b0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
1e9c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1e9d0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1e9e0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
1e9f0 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
1ea00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1ea10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1ea20 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1ea30 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
1ea40 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
1ea50 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
1ea60 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
1ea70 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
1ea80 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
1ea90 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
1eaa0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
1eab0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1eac0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
1ead0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
1eae0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
1eaf0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1eb00 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
1eb10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1eb20 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
1eb30 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
1eb40 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
1eb50 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
1eb60 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
1eb70 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
1eb80 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
1eb90 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
1eba0 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
1ebb0 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
1ebc0 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
1ebd0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
1ebe0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
1ebf0 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
1ec00 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1ec10 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1ec20 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
1ec30 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1ec40 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
1ec50 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
1ec60 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
1ec70 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1ec80 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1ec90 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1eca0 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
1ecb0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
1ecc0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1ecd0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1ece0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
1ecf0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1ed00 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
1ed10 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
1ed20 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
1ed30 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
1ed40 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1ed50 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
1ed60 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
1ed70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ed80 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1ed90 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1eda0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
1edb0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1edc0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1edd0 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
1ede0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
1edf0 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
1ee00 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
1ee10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1ee20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ee30 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
1ee40 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
1ee50 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
1ee60 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1ee70 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
1ee80 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
1ee90 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
1eea0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1eeb0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
1eec0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
1eed0 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
1eee0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
1eef0 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
1ef00 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
1ef10 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
1ef20 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
1ef30 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
1ef40 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
1ef50 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1ef60 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
1ef70 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
1ef80 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
1ef90 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1efa0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
1efb0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1efc0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
1efd0 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
1efe0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1eff0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1f000 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
1f010 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
1f020 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
1f030 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
1f040 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
1f050 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
1f060 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1f070 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
1f080 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
1f090 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
1f0a0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
1f0b0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
1f0c0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
1f0d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1f0e0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
1f0f0 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
1f100 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
1f110 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
1f120 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
1f130 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1f140 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
1f150 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1f160 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
1f170 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1f180 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
1f190 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
1f1a0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
1f1b0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
1f1c0 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
1f1d0 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
1f1e0 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
1f1f0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
1f200 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
1f210 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
1f220 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
1f230 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
1f240 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
1f250 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
1f260 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
1f270 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1f280 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
1f290 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
1f2a0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
1f2b0 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
1f2c0 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
1f2d0 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
1f2e0 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
1f2f0 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
1f300 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
1f310 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
1f320 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1f330 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
1f340 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
1f350 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
1f360 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
1f370 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
1f380 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
1f390 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
1f3a0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
1f3b0 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
1f3c0 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
1f3d0 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
1f3e0 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
1f3f0 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
1f400 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
1f410 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
1f420 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
1f430 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
1f440 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1f450 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
1f460 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
1f470 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
1f480 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
1f490 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1f4a0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
1f4b0 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
1f4c0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1f4d0 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
1f4e0 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
1f4f0 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
1f500 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
1f510 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
1f520 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
1f530 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
1f540 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
1f550 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
1f560 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
1f570 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
1f580 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
1f590 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
1f5a0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
1f5b0 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
1f5c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1f5d0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
1f5e0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
1f5f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1f600 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
1f610 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
1f620 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
1f630 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
1f640 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
1f650 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
1f660 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
1f670 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1f680 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
1f690 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f6a0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1f6b0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1f6c0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1f6d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f6e0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1f6f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1f700 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
1f710 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1f720 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1f730 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1f740 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1f750 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1f760 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1f770 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1f780 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1f790 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1f7a0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
1f7b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1f7c0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
1f7d0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
1f7e0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
1f7f0 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
1f800 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
1f810 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
1f820 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
1f830 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
1f840 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1f850 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
1f860 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
1f870 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
1f880 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
1f890 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
1f8a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1f8b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
1f8c0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1f8d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1f8e0 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
1f8f0 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
1f900 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1f910 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
1f920 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
1f930 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
1f940 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
1f950 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
1f960 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
1f970 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
1f980 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
1f990 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
1f9a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
1f9b0 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
1f9c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
1f9d0 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
1f9e0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
1f9f0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
1fa00 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1fa10 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1fa20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1fa30 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1fa40 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1fa50 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1fa60 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1fa70 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1fa80 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1fa90 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1faa0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1fab0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1fac0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1fad0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1fae0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1faf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fb00 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1fb10 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1fb20 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1fb30 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1fb40 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1fb50 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1fb60 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1fb70 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1fb80 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1fb90 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1fba0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1fbb0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1fbc0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1fbd0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1fbe0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1fbf0 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1fc00 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1fc10 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1fc20 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
1fc30 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
1fc40 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
1fc50 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1fc60 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1fc70 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1fc80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1fc90 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1fca0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1fcb0 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1fcc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fcd0 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1fce0 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1fcf0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1fd00 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
1fd10 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1fd20 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1fd30 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
1fd40 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1fd50 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1fd60 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
1fd70 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
1fd80 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
1fd90 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
1fda0 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
1fdb0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1fdc0 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
1fdd0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1fde0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1fdf0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1fe00 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
1fe10 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
1fe20 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
1fe30 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
1fe40 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
1fe50 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
1fe60 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1fe70 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
1fe80 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
1fe90 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
1fea0 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
1feb0 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
1fec0 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
1fed0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
1fee0 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
1fef0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1ff00 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
1ff10 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
1ff20 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
1ff30 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1ff40 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1ff50 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
1ff60 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
1ff70 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1ff80 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
1ff90 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1ffa0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1ffb0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1ffc0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1ffd0 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
1ffe0 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
1fff0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
20000 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
20010 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
20020 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20030 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
20040 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
20050 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
20060 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
20070 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
20080 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
20090 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
200a0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
200b0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
200c0 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
200d0 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
200e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
200f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20100 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
20110 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
20120 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
20130 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
20140 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
20150 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
20160 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
20170 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20180 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
20190 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
201a0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
201b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
201c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
201d0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
201e0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
201f0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20200 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20210 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20220 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
20230 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
20240 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20250 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20260 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20270 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
20280 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
20290 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
202a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
202b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
202c0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
202d0 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
202e0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
202f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20300 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20310 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
20320 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
20330 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
20340 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20350 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20360 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
20370 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
20380 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
20390 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
203a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
203b0 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
203c0 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
203d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
203e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
203f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20400 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
20410 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
20420 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
20430 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20450 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
20460 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
20470 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20480 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
204a0 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
204b0 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
204c0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
204d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
204e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
204f0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
20500 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
20510 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20520 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20530 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
20540 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
20550 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
20560 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
20570 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
20580 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
20590 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
205a0 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
205b0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
205c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
205d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
205e0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
205f0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
20600 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
20610 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20620 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
20630 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
20640 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
20650 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20660 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20670 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
20680 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
20690 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
206a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
206b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
206c0 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
206d0 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
206e0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
206f0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
20700 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
20710 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
20720 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
20730 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20740 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
20750 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20760 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
20770 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
20780 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20790 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
207a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
207b0 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
207c0 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
207d0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
207e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
207f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20800 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
20810 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
20820 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
20830 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
20840 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20850 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
20860 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
20870 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
20880 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
208a0 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
208b0 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
208c0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
208d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
208e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
208f0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
20900 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
20910 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
20920 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20930 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
20940 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
20950 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
20960 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20970 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20980 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
20990 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
209a0 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
209b0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
209c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
209d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
209e0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
209f0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
20a00 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
20a10 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
20a20 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
20a30 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
20a40 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
20a50 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
20a60 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
20a70 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
20a80 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
20a90 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
20aa0 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
20ab0 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
20ac0 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
20ad0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
20ae0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
20af0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
20b00 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
20b10 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
20b20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
20b30 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
20b40 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
20b50 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
20b60 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
20b70 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
20b80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20b90 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
20ba0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
20bb0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
20bc0 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
20bd0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
20be0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
20bf0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
20c00 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
20c10 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
20c20 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
20c30 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
20c40 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
20c50 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
20c60 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
20c70 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
20c80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
20c90 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
20ca0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
20cb0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
20cc0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
20cd0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
20ce0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
20cf0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
20d00 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
20d10 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
20d20 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
20d30 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
20d40 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
20d50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
20d60 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
20d70 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
20d80 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
20d90 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
20da0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
20db0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
20dc0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
20dd0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
20de0 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
20df0 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
20e00 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
20e10 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
20e20 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
20e30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
20e40 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
20e50 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
20e60 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
20e70 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
20e80 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
20e90 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
20ea0 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
20eb0 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
20ec0 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
20ed0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
20ee0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
20ef0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
20f00 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
20f10 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
20f20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
20f30 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
20f40 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
20f50 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
20f60 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
20f70 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
20f80 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
20f90 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
20fa0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
20fb0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
20fc0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
20fd0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
20fe0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
20ff0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
21000 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
21010 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
21020 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
21030 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
21040 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
21050 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
21060 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
21070 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
21080 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
21090 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
210a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
210b0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
210c0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
210d0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
210e0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
210f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
21100 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
21110 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
21120 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
21130 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
21140 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
21150 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
21160 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
21170 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
21180 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
21190 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
211a0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
211b0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
211c0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
211d0 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45  _API SQLITE_EXPE
211e0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53  RIMENTAL void *S
211f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
21200 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
21210 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
21220 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
21230 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
21240 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
21250 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
21260 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
21270 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
21280 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
21290 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
212a0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
212b0 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
212c0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
212d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
212e0 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
212f0 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
21300 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
21310 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
21320 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
21330 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
21340 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
21350 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
21360 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
21370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
21380 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
21390 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
213a0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
213b0 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
213c0 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
213d0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
213e0 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
213f0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
21400 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
21410 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
21420 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21430 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
21440 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61  meter N is the a
21450 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65  pproximate numbe
21460 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
21470 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
21480 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
21490 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
214a0 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
214b0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
214c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20  the callback X. 
214d0 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74   ^If N is less t
214e0 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65  han one then the
214f0 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e   progress.** han
21500 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  dler is disabled
21510 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
21520 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
21530 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
21540 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
21550 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
21560 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
21570 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
21580 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
21590 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
215a0 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
215b0 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
215c0 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
215d0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
215e0 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
215f0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
21600 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
21610 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
21620 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
21630 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
21640 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
21650 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
21660 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
21670 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
21680 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
21690 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
216a0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
216b0 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
216c0 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
216d0 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
216e0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
216f0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
21700 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
21710 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
21720 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
21730 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21740 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
21750 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
21760 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
21770 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
21780 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21790 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
217a0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
217b0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
217c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
217d0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
217e0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
217f0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
21800 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
21810 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
21820 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  LL sqlite3_progr
21830 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
21840 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
21850 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
21860 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21870 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
21880 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
21890 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  tion.** CONSTRUC
218a0 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
218b0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
218c0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
218d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
218e0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
218f0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
21900 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
21910 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
21920 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
21930 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
21940 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21950 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
21960 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
21970 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
21980 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
21990 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
219a0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
219b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
219c0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
219d0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
219e0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
219f0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
21a00 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
21a10 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
21a20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
21a30 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
21a40 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
21a50 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
21a60 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
21a70 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
21a80 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
21a90 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
21aa0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
21ab0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
21ac0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
21ad0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
21ae0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
21af0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
21b00 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
21b10 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
21b20 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
21b30 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
21b40 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
21b50 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
21b60 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
21b70 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
21b80 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
21b90 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
21ba0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
21bb0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
21bc0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
21bd0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
21be0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
21bf0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
21c00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
21c10 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77  fault encoding w
21c20 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72  ill be UTF-8 for
21c30 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74   databases creat
21c40 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69  ed using.** sqli
21c50 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
21c60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
21c70 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65    ^The default e
21c80 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61  ncoding for data
21c90 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  bases.** created
21ca0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f   using sqlite3_o
21cb0 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20  pen16() will be 
21cc0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
21cd0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
21ce0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
21cf0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
21d00 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
21d10 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
21d20 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
21d30 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
21d40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
21d50 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
21d60 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
21d70 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
21d80 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
21d90 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
21da0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
21db0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
21dc0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
21dd0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
21de0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
21df0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
21e00 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
21e10 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
21e20 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
21e30 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
21e40 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
21e50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
21e60 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
21e70 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
21e80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
21e90 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
21ea0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
21eb0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
21ec0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
21ed0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
21ee0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
21ef0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
21f00 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
21f10 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
21f20 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
21f30 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
21f40 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
21f50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
21f60 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
21f70 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
21f80 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
21f90 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
21fa0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
21fb0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
21fc0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
21fd0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
21fe0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
21ff0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
22000 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
22010 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
22020 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
22030 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
22040 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
22050 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
22060 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
22070 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
22080 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
22090 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
220a0 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
220b0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
220c0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
220d0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
220e0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
220f0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
22100 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
22110 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
22120 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
22130 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
22140 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
22150 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
22160 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22170 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
22180 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
22190 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
221a0 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
221b0 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
221c0 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
221d0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
221e0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
221f0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
22200 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
22210 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
22220 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
22230 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
22240 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
22250 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22260 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
22270 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
22280 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
22290 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
222a0 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
222b0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
222c0 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
222d0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
222e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
222f0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
22300 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
22310 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
22320 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
22330 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
22340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
22350 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
22360 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
22370 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
22380 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
22390 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
223a0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
223b0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
223c0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
223d0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
223e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
223f0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
22400 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
22410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
22420 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
22430 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
22440 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
22450 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
22460 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
22470 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
22480 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
22490 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
224a0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
224b0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
224c0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
224d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
224e0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
224f0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
22500 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
22510 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
22520 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
22530 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
22540 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
22550 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
22560 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
22570 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
22580 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
22590 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
225a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
225b0 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
225c0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
225d0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
225e0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
225f0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
22600 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
22610 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
22620 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
22630 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
22640 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
22650 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
22660 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
22670 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
22680 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
22690 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
226a0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
226b0 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
226c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
226d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
226e0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
226f0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
22700 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
22710 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
22720 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
22730 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
22740 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
22750 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
22760 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
22770 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
22780 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
22790 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
227a0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
227b0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
227c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
227d0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
227e0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
227f0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
22800 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
22810 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
22820 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
22830 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
22840 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
22850 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
22860 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
22870 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
22880 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
22890 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
228a0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
228b0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
228c0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
228d0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
228e0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
228f0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
22900 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
22910 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22920 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
22930 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
22940 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
22950 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
22960 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
22970 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
22980 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
22990 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
229a0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
229b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
229c0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
229d0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
229e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
229f0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
22a00 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
22a10 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
22a20 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
22a30 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
22a40 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
22a50 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
22a60 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
22a70 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
22a80 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
22a90 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
22aa0 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
22ab0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
22ac0 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
22ad0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
22ae0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
22af0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
22b00 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
22b10 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
22b20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
22b30 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
22b40 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
22b50 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
22b60 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
22b70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
22b80 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
22b90 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
22ba0 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
22bb0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
22bc0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
22bd0 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
22be0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
22bf0 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
22c00 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
22c10 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
22c20 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
22c30 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
22c40 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
22c50 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
22c60 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
22c70 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
22c80 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
22c90 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
22ca0 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
22cb0 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
22cc0 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
22cd0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
22ce0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
22cf0 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
22d00 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
22d10 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
22d20 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
22d30 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
22d40 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
22d50 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
22d60 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
22d70 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
22d80 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
22d90 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
22da0 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
22db0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
22dc0 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
22dd0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
22de0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
22df0 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
22e00 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
22e10 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
22e20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
22e30 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
22e40 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
22e50 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
22e60 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
22e70 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
22e80 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
22e90 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
22ea0 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
22eb0 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
22ec0 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
22ed0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
22ee0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
22ef0 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
22f00 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
22f10 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
22f20 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
22f30 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
22f40 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
22f50 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
22f60 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
22f70 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
22f80 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
22f90 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
22fa0 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
22fb0 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
22fc0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
22fd0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
22fe0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
22ff0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
23000 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
23010 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
23020 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
23030 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
23040 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
23050 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
23060 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
23070 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
23080 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
23090 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
230a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
230b0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
230c0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
230d0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
230e0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
230f0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
23100 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
23110 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
23120 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
23130 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
23140 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
23150 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
23160 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
23170 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
23180 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
23190 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
231a0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
231b0 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
231c0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
231d0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
231e0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
231f0 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
23200 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
23210 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23220 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
23230 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
23240 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
23250 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
23260 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
23270 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
23280 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
23290 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
232a0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
232b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
232c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
232d0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
232e0 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
232f0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
23300 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
23310 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
23320 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
23330 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
23340 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
23350 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
23360 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
23370 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
23380 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
23390 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
233a0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
233b0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
233c0 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
233d0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
233e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
233f0 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
23400 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
23410 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
23420 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
23430 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
23440 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
23450 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
23460 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
23470 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
23480 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
23490 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
234a0 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
234b0 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
234c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
234d0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
234e0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
234f0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
23500 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
23510 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
23520 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
23530 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
23540 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
23550 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
23560 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
23570 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
23580 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
23590 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
235a0 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
235b0 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
235c0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
235d0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
235e0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
235f0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
23600 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
23610 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
23620 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
23630 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
23640 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
23650 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
23660 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
23670 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
23680 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
23690 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
236a0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
236b0 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
236c0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
236d0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
236e0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
236f0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
23700 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
23710 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
23720 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
23730 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
23740 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
23750 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
23760 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
23770 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
23780 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
23790 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
237a0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
237b0 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
237c0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
237d0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
237e0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
237f0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
23800 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
23810 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
23820 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
23830 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
23840 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
23850 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
23860 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
23870 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
23880 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
23890 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
238a0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
238b0 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
238c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
238d0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
238e0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
238f0 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
23900 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
23910 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
23920 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
23930 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
23940 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
23950 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
23960 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
23970 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
23980 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
23990 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
239a0 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
239b0 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
239c0 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
239d0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
239e0 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
239f0 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
23a00 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
23a10 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
23a20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
23a30 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
23a40 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
23a50 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
23a60 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
23a70 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
23a80 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
23a90 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
23aa0 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
23ab0 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
23ac0 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
23ad0 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
23ae0 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
23af0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
23b00 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
23b10 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
23b20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
23b30 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
23b40 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
23b50 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
23b60 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
23b70 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
23b80 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
23b90 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
23ba0 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
23bb0 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
23bc0 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
23bd0 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
23be0 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
23bf0 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
23c00 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
23c10 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
23c20 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
23c30 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
23c40 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
23c50 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
23c60 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
23c70 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
23c80 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
23c90 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
23ca0 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
23cb0 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
23cc0 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
23cd0 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
23ce0 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
23cf0 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
23d00 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
23d10 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
23d20 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
23d30 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
23d40 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
23d50 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
23d60 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
23d70 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
23d80 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
23d90 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
23da0 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
23db0 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
23dc0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
23dd0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
23de0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
23df0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
23e00 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
23e10 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
23e20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
23e30 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
23e40 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
23e50 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
23e60 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
23e70 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
23e80 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
23e90 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
23ea0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
23eb0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
23ec0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
23ed0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
23ee0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
23ef0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
23f00 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
23f10 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
23f20 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
23f30 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
23f40 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
23f50 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
23f60 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
23f70 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
23f80 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
23f90 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
23fa0 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
23fb0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
23fc0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
23fd0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
23fe0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
23ff0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
24000 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
24010 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
24020 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
24030 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
24040 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
24050 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
24060 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
24070 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
24080 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
24090 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
240a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
240b0 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
240c0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
240d0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
240e0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
240f0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
24100 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
24110 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
24120 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
24130 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
24140 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
24150 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
24160 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
24170 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
24180 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
24190 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
241a0 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
241b0 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
241c0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
241d0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
241e0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
241f0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
24200 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
24210 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
24220 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
24230 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
24240 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
24250 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
24260 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
24270 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
24280 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
24290 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
242a0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
242b0 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
242c0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
242d0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
242e0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
242f0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
24300 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
24310 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
24320 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
24330 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
24340 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
24350 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24360 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
24370 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
24380 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
24390 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
243a0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
243b0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
243c0 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
243d0 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
243e0 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
243f0 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
24400 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
24410 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
24420 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
24430 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
24440 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
24450 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
24460 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
24470 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
24480 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
24490 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
244a0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
244b0 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
244c0 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
244d0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
244e0 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
244f0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
24500 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
24510 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
24520 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
24530 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
24540 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
24550 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
24560 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
24570 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
24580 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
24590 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
245a0 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
245b0 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
245c0 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
245d0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
245e0 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
245f0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
24600 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
24610 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
24620 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
24630 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
24640 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
24650 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
24660 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
24670 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
24680 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
24690 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
246a0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
246b0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
246c0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
246d0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
246e0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
246f0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
24700 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
24710 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
24720 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24730 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
24740 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
24750 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
24760 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
24770 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
24780 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
24790 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
247a0 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
247b0 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
247c0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
247d0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
247e0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
247f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
24800 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
24810 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
24820 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
24830 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
24840 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
24850 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
24860 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
24870 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
24880 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
24890 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
248a0 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
248b0 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
248c0 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
248d0 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
248e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
248f0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
24900 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ory].*/.SQLITE_A
24910 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
24920 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70  DCALL sqlite3_op
24930 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
24940 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
24950 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
24960 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
24970 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
24980 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
24990 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
249a0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
249b0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
249c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65  CALL sqlite3_ope
249d0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
249e0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
249f0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
24a00 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
24a10 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
24a20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
24a30 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
24a40 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
24a50 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
24a60 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f  TDCALL sqlite3_o
24a70 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
24a80 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
24a90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
24aa0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
24ab0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
24ac0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
24ad0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
24ae0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
24af0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
24b00 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
24b10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
24b20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
24b30 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
24b40 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
24b50 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
24b60 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
24b70 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
24b80 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
24b90 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
24ba0 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
24bb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
24bc0 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
24bd0 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
24be0 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
24bf0 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
24c00 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
24c10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
24c20 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
24c30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
24c40 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
24c50 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
24c60 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
24c70 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
24c80 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
24c90 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
24ca0 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
24cb0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
24cc0 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
24cd0 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
24ce0 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
24cf0 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
24d00 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
24d10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
24d20 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
24d30 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
24d40 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
24d50 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
24d60 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
24d70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
24d80 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
24d90 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
24da0 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
24db0 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
24dc0 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
24dd0 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
24de0 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
24df0 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
24e00 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
24e10 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
24e20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
24e30 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
24e40 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
24e50 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
24e60 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
24e70 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
24e80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
24e90 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24ea0 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
24eb0 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
24ec0 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
24ed0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
24ee0 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
24ef0 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
24f00 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
24f10 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
24f20 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
24f30 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
24f40 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
24f50 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
24f60 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
24f70 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
24f80 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
24f90 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
24fa0 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
24fb0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
24fc0 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
24fd0 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
24fe0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
24ff0 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
25000 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
25010 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
25020 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
25030 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
25040 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
25050 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
25060 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
25070 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
25080 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
25090 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
250a0 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
250b0 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
250c0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
250d0 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
250e0 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
250f0 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
25100 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
25110 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
25120 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
25130 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
25140 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
25150 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
25160 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
25170 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
25180 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
25190 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
251a0 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
251b0 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
251c0 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
251d0 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
251e0 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
251f0 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
25200 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
25210 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
25220 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
25230 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
25240 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
25250 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
25260 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
25270 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
25280 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
25290 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
252a0 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
252b0 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
252c0 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
252d0 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
252e0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
252f0 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
25300 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
25310 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
25320 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
25330 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
25340 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
25350 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
25360 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
25370 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
25380 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
25390 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
253a0 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
253b0 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49  r *zParam);.SQLI
253c0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
253d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
253e0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
253f0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
25400 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
25410 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
25420 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  t);.SQLITE_API s
25430 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c  qlite3_int64 SQL
25440 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
25450 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
25460 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
25470 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
25480 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
25490 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
254a0 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
254b0 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
254c0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lite3.**.** ^If 
254d0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
254e0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
254f0 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ll associated wi
25500 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  th .** [database
25510 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66   connection] D f
25520 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ailed, then the 
25530 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
25540 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  D) interface.** 
25550 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
25560 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
25570 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72  ] or [extended r
25580 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
25590 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c  that.** API call
255a0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74  ..** If the most
255b0 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
255c0 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c   was successful,
255d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
255e0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
255f0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
25600 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
25610 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
25620 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
25630 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
25640 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
25650 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
25660 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
25670 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
25680 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
25690 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
256a0 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
256b0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
256c0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
256d0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
256e0 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
256f0 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
25700 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
25710 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
25720 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
25730 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
25740 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
25750 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
25760 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
25770 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
25780 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
25790 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
257a0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
257b0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
257c0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
257d0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
257e0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
257f0 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
25800 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
25810 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
25820 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
25830 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
25840 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
25850 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
25860 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
25870 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25880 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
25890 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
258a0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
258b0 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
258c0 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
258d0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
258e0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
258f0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
25900 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
25910 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
25920 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
25930 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
25940 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
25950 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
25960 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
25970 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
25980 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
25990 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
259a0 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
259b0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
259c0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
259d0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
259e0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
259f0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
25a00 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
25a10 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
25a20 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
25a30 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
25a40 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
25a50 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
25a60 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
25a70 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
25a80 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
25a90 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
25aa0 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
25ab0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
25ac0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25ad0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
25ae0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
25af0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
25b00 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
25b10 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
25b20 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
25b30 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
25b40 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
25b50 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
25b60 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
25b70 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
25b80 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
25b90 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
25ba0 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
25bb0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
25bc0 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
25bd0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
25be0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
25bf0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
25c00 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
25c10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
25c20 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
25c30 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
25c40 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
25c50 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
25c60 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
25c70 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
25c80 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
25c90 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
25ca0 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  db);.SQLITE_API 
25cb0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
25cc0 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  LL sqlite3_exten
25cd0 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
25ce0 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
25cf0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
25d00 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
25d10 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
25d20 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
25d30 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
25d40 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
25d50 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
25d60 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
25d70 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
25d80 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
25d90 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  L sqlite3_errstr
25da0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
25db0 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64  PI3REF: Prepared
25dc0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
25dd0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
25de0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25df0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
25e00 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
25e10 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
25e20 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
25e30 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
25e40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
25e50 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f  t.** has been co
25e60 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61  mpiled into bina
25e70 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72  ry form and is r
25e80 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75  eady to be evalu
25e90 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  ated..**.** Thin
25ea0 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74  k of each SQL st
25eb0 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70  atement as a sep
25ec0 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70  arate computer p
25ed0 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20  rogram.  The.** 
25ee0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
25ef0 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  t is source code
25f00 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74  .  A prepared st
25f10 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a  atement object .
25f20 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c  ** is the compil
25f30 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20  ed object code. 
25f40 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65   All SQL must be
25f50 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
25f60 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  a.** prepared st
25f70 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69  atement before i
25f80 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a  t can be run..**
25f90 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63  .** The life-cyc
25fa0 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  le of a prepared
25fb0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
25fc0 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c  t usually goes l
25fd0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
25fe0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
25ff0 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64  ate the prepared
26000 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
26010 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
26020 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a  _prepare_v2()]..
26030 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
26040 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  ues to [paramete
26050 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
26060 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
26070 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
26080 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
26090 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
260a0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
260b0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
260c0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
260d0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
260e0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
260f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
26100 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
26110 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
26120 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
26130 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
26140 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
26150 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
26160 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
26170 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
26180 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
26190 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
261a0 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
261b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
261c0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
261d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
261e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
261f0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
26200 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
26210 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
26220 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
26230 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
26240 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
26250 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
26260 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
26270 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
26280 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
26290 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
262a0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
262b0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
262c0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
262d0 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
262e0 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
262f0 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
26300 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
26310 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
26320 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
26330 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
26340 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
26350 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
26360 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
26370 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
26380 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
26390 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
263a0 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
263b0 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
263c0 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
263d0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
263e0 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
263f0 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
26400 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
26410 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
26420 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
26430 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
26440 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
26450 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
26460 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
26470 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
26480 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
26490 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
264a0 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
264b0 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
264c0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
264d0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
264e0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
264f0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
26500 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
26510 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
26520 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
26530 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
26540 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
26550 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
26560 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
26570 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
26580 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
26590 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
265a0 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
265b0 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
265c0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
265d0 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
265e0 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
265f0 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
26600 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
26610 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
26620 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
26630 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
26640 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
26650 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
26660 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
26670 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
26680 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
26690 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
266a0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
266b0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
266c0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
266d0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
266e0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
266f0 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
26700 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
26710 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
26720 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
26730 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
26740 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
26750 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
26760 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
26770 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
26780 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
26790 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
267a0 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
267b0 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
267c0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
267d0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
267e0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
267f0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
26800 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
26810 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
26820 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
26830 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
26840 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
26850 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
26860 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
26870 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
26880 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
26890 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
268a0 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
268b0 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
268c0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
268d0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
268e0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
268f0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
26900 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
26910 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
26920 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
26930 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
26940 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
26950 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
26960 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
26970 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51   releases..*/.SQ
26980 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
26990 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
269a0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
269b0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
269c0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
269d0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
269e0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
269f0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
26a00 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
26a10 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
26a20 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
26a30 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
26a40 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
26a50 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
26a60 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
26a70 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
26a80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
26a90 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
26aa0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
26ab0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
26ac0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
26ad0 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
26ae0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
26af0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
26b00 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
26b10 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
26b20 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
26b30 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
26b40 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
26b50 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26b60 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
26b70 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
26b80 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
26b90 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
26ba0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
26bb0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
26bc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
26bd0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
26be0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
26bf0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
26c00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26c10 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
26c20 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
26c30 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
26c40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26c50 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
26c60 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
26c70 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
26c80 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
26c90 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
26ca0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
26cb0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
26cc0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
26cd0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
26ce0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
26cf0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
26d00 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
26d10 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
26d20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
26d30 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
26d40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
26d50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
26d60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
26d70 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
26d80 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26d90 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
26da0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
26db0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
26dc0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26dd0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
26de0 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
26df0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
26e00 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
26e10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26e20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
26e30 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
26e40 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
26e50 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
26e60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26e70 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
26e80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
26e90 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
26ea0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
26eb0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
26ec0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
26ed0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
26ee0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
26ef0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
26f00 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
26f10 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
26f20 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
26f30 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
26f40 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
26f50 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
26f60 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
26f70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
26f80 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
26f90 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
26fa0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26fb0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
26fc0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26fd0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
26fe0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
26ff0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
27000 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
27010 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
27020 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
27030 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
27040 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
27050 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
27060 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
27070 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
27080 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
27090 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
270a0 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
270b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
270c0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
270d0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
270e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
270f0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
27100 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
27110 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
27120 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
27130 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
27140 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27150 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
27160 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
27170 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
27180 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
27190 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
271a0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
271b0 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
271c0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
271d0 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
271e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
271f0 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
27200 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27210 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
27220 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
27230 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
27240 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
27250 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
27260 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
27270 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
27280 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  S]] ^(<dt>SQLITE
27290 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
272a0 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  READS</dt>.** <d
272b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
272c0 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72  mber of auxiliar
272d0 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73  y worker threads
272e0 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a   that a single.*
272f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
27300 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74  ement] may start
27310 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
27320 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
27330 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
27340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27350 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
27360 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
27370 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
27380 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
27390 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
273a0 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
273b0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
273c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
273d0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
273e0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
273f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
27400 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
27410 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
27420 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
27430 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
27440 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
27450 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27460 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
27470 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
27480 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27490 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
274a0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
274b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
274c0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
274d0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
274e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
274f0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
27500 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
27510 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27520 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
27530 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
27540 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27550 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
27560 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31  ADS           11
27570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27580 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
27590 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
275a0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
275b0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
275c0 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
275d0 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55  lite3.** CONSTRU
275e0 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
275f0 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  mt.**.** To exec
27600 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
27610 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
27620 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
27630 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
27640 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
27650 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
27660 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
27670 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
27680 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
27690 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
276a0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
276b0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
276c0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
276d0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
276e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
276f0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
27700 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
27710 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
27720 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
27730 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
27740 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
27750 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
27760 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
27770 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
27780 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
27790 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
277a0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
277b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
277c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
277d0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
277e0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
277f0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
27800 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
27810 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27820 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
27830 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
27840 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
27850 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
27860 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
27870 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
27880 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
27890 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
278a0 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
278b0 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
278c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
278d0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
278e0 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
278f0 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
27900 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
27910 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
27920 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
27930 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
27940 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
27950 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
27960 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
27970 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
27980 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
27990 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
279a0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
279b0 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
279c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
279d0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
279e0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
279f0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
27a00 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
27a10 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
27a20 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
27a30 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
27a40 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
27a50 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
27a60 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
27a70 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
27a80 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
27a90 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
27aa0 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
27ab0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
27ac0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
27ad0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
27ae0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
27af0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
27b00 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
27b10 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
27b20 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
27b30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27b40 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
27b50 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
27b60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
27b70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
27b80 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
27b90 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
27ba0 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
27bb0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
27bc0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
27bd0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
27be0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
27bf0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
27c00 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
27c10 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
27c20 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
27c30 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
27c40 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
27c50 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
27c60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
27c70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
27c80 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
27c90 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
27ca0 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
27cb0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
27cc0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
27cd0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
27ce0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
27cf0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
27d00 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
27d10 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
27d20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
27d30 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
27d40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
27d50 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
27d60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27d70 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
27d80 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
27d90 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
27da0 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
27db0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
27dc0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
27dd0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
27de0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
27df0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
27e00 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
27e10 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
27e20 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
27e30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27e40 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
27e50 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
27e60 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
27e70 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
27e80 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
27e90 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
27ea0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
27eb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27ec0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
27ed0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
27ee0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
27ef0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
27f00 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
27f10 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
27f20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
27f30 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
27f40 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
27f50 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
27f60 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
27f70 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
27f80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
27f90 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
27fa0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
27fb0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
27fc0 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
27fd0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
27fe0 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
27ff0 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
28000 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
28010 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
28020 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
28030 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
28040 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
28050 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
28060 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
28070 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
28080 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
28090 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
280a0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
280b0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
280c0 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
280d0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
280e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
280f0 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
28100 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
28110 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
28120 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
28130 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
28140 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
28150 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
28160 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
28170 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
28180 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
28190 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
281a0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
281b0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
281c0 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
281d0 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
281e0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
281f0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
28200 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
28210 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
28220 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
28230 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
28240 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
28250 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
28260 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
28270 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
28280 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
28290 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
282a0 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
282b0 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
282c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
282d0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
282e0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
282f0 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
28300 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
28310 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
28320 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
28330 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
28340 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
28350 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
28360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28370 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
28380 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
28390 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
283a0 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
283b0 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
283c0 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
283d0 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
283e0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
283f0 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
28400 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
28410 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
28420 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
28430 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
28440 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
28450 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
28460 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
28470 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
28480 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
28490 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
284a0 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
284b0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
284c0 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ol>.*/.SQLITE_AP
284d0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
284e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65  CALL sqlite3_pre
284f0 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
28500 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
28510 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
28520 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
28530 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
28540 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
28550 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
28560 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
28570 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
28580 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
28590 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
285a0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
285b0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
285c0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
285d0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
285e0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
285f0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
28600 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
28610 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
28620 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
28630 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
28640 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  L sqlite3_prepar
28650 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
28660 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
28670 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
28680 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
28690 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
286a0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
286b0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
286c0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
286d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
286e0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
286f0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
28700 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
28710 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
28720 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
28730 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28740 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
28750 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
28760 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
28770 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
28780 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
28790 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
287a0 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  L sqlite3_prepar
287b0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
287c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
287d0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
287e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
287f0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
28800 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
28810 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
28820 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
28830 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
28840 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
28850 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
28860 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
28870 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
28880 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
28890 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
288a0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
288b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
288c0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
288d0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
288e0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
288f0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
28900 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  L sqlite3_prepar
28910 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
28920 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
28930 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
28940 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28950 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
28960 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
28970 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
28980 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
28990 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
289a0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
289b0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
289c0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
289d0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
289e0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
289f0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
28a00 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
28a10 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
28a20 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
28a30 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
28a40 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
28a50 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
28a60 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
28a70 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
28a80 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
28a90 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
28aa0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
28ab0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
28ac0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
28ad0 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
28ae0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
28af0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28b00 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
28b10 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
28b20 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
28b30 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
28b40 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
28b50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28b60 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  6_v2()]..*/.SQLI
28b70 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
28b80 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
28b90 4c 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71  L sqlite3_sql(sq
28ba0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
28bb0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28bc0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
28bd0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
28be0 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
28bf0 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
28c00 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
28c10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28c20 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
28c30 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
28c40 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
28c50 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
28c60 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
28c70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28c80 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
28c90 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
28ca0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
28cb0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28cc0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
28cd0 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
28ce0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
28cf0 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
28d00 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
28d10 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
28d20 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
28d30 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
28d40 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
28d50 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
28d60 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
28d70 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
28d80 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
28d90 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
28da0 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
28db0 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
28dc0 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
28dd0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
28de0 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
28df0 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
28e00 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
28e10 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
28e20 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
28e30 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
28e40 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
28e50 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
28e60 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
28e70 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
28e80 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
28e90 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
28ea0 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
28eb0 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
28ec0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
28ed0 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
28ee0 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
28ef0 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
28f00 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
28f10 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
28f20 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
28f30 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
28f40 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
28f50 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
28f60 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
28f70 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
28f80 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
28f90 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
28fa0 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
28fb0 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
28fc0 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
28fd0 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
28fe0 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
28ff0 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
29000 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
29010 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
29020 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
29030 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
29040 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
29050 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
29060 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
29070 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
29080 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
29090 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
290a0 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
290b0 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
290c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
290d0 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
290e0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
290f0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
29100 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
29110 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c   on disk..*/.SQL
29120 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
29130 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
29140 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
29150 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
29160 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
29170 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
29180 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
29190 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
291a0 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48  en Reset.** METH
291b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
291c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
291d0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_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 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
29200 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
29210 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29220 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
29230 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
29240 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
29250 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
29260 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
29270 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
29280 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
29290 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
292a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
292b0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
292c0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
292d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
292e0 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
292f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
29300 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
29310 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
29320 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
29330 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
29340 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
29350 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
29360 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
29370 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
29380 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
29390 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
293a0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
293b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
293c0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
293d0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
293e0 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
293f0 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
29400 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
29410 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
29420 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
29430 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
29440 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
29450 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
29460 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
29470 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
29480 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
29490 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
294a0 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
294b0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
294c0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
294d0 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45   open..*/.SQLITE
294e0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
294f0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
29500 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65  stmt_busy(sqlite
29510 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
29520 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
29530 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
29540 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
29550 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
29560 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
29570 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
29580 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
29590 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
295a0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
295b0 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
295c0 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
295d0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
295e0 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
295f0 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
29600 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
29610 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
29620 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
29630 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
29640 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
29650 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
29660 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
29670 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
29680 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
29690 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
296a0 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
296b0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
296c0 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
296d0 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
296e0 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
296f0 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
29700 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
29710 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
29720 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
29730 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
29740 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
29750 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
29760 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29770 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
29780 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
29790 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
297a0 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
297b0 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
297c0 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
297d0 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
297e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
297f0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
29800 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e  _value_dup()] in
29810 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
29820 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74  sed to construct
29830 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65   a new .** prote
29840 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29850 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f  ue from an unpro
29860 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29870 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
29880 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
29890 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
298a0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
298b0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
298c0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
298d0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
298e0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
298f0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
29900 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29910 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
29920 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
29930 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
29940 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29950 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
29960 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
29970 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
29980 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
29990 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
299a0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
299b0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
299c0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
299d0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
299e0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
299f0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
29a00 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
29a10 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
29a20 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
29a30 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
29a40 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
29a50 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
29a60 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
29a70 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
29a80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
29a90 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
29aa0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
29ab0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
29ac0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
29ad0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
29ae0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
29af0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
29b00 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
29b10 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
29b20 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
29b30 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
29b40 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
29b50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
29b60 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
29b70 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
29b80 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
29b90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
29ba0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
29bb0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
29bc0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
29bd0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
29be0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
29bf0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
29c00 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
29c10 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
29c20 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
29c30 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
29c40 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
29c50 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
29c60 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
29c70 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
29c80 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29c90 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
29ca0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
29cb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
29cc0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
29cd0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
29ce0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
29cf0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
29d00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
29d10 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
29d20 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
29d30 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
29d40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29d50 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
29d60 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
29d70 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
29d80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
29d90 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
29da0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
29db0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
29dc0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
29dd0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
29de0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
29df0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
29e00 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
29e10 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
29e20 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
29e30 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
29e40 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
29e50 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
29e60 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
29e70 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
29e80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29e90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
29ea0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
29eb0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
29ec0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
29ed0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
29ee0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
29ef0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
29f00 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
29f10 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
29f20 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
29f30 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
29f40 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
29f50 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
29f60 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
29f70 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
29f80 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
29f90 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
29fa0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
29fb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
29fc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
29fd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29fe0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
29ff0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
2a000 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
2a010 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
2a020 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
2a030 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
2a040 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
2a050 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
2a060 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
2a070 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
2a080 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
2a090 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2a0a0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49  3_stmt.**.** ^(I
2a0b0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
2a0c0 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
2a0d0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
2a0e0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
2a0f0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
2a100 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
2a110 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
2a120 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
2a130 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
2a140 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
2a150 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2a160 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
2a170 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
2a180 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
2a190 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
2a1a0 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
2a1b0 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
2a1c0 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
2a1d0 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
2a1e0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
2a1f0 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
2a200 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
2a210 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
2a220 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
2a230 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
2a240 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
2a250 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
2a260 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
2a270 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
2a280 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
2a290 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2a2a0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
2a2b0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
2a2c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2a2d0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
2a2e0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2a2f0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
2a300 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
2a310 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
2a320 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
2a330 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
2a340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a350 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
2a360 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
2a370 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2a380 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2a390 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
2a3a0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
2a3b0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
2a3c0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
2a3d0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
2a3e0 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
2a3f0 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
2a400 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
2a410 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
2a420 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2a430 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
2a440 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
2a450 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
2a460 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
2a470 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
2a480 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
2a490 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
2a4a0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
2a4b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2a4c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2a4d0 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
2a4e0 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
2a4f0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
2a500 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
2a510 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
2a520 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
2a530 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
2a540 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
2a550 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
2a560 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
2a570 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2a580 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
2a590 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
2a5a0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
2a5b0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
2a5c0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
2a5d0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
2a5e0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2a5f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2a600 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2a610 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2a620 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
2a630 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2a640 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
2a650 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
2a660 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
2a670 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
2a680 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
2a690 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
2a6a0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2a6b0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
2a6c0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
2a6d0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
2a6e0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
2a6f0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2a700 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2a710 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
2a720 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
2a730 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
2a740 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
2a750 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
2a760 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
2a770 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2a780 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
2a790 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2a7a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2a7b0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2a7c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2a7d0 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
2a7e0 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
2a7f0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
2a800 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
2a810 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
2a820 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2a830 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
2a840 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2a850 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2a860 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2a870 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
2a880 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
2a890 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2a8a0 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
2a8b0 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
2a8c0 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
2a8d0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a8e0 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
2a8f0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2a900 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2a910 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e  nd_text64() then
2a920 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74  .** that paramet
2a930 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
2a940 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
2a950 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
2a960 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
2a970 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
2a980 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
2a990 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
2a9a0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
2a9b0 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
2a9c0 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
2a9d0 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
2a9e0 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
2a9f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
2aa00 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
2aa10 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
2aa20 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
2aa30 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
2aa40 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
2aa50 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
2aa60 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
2aa70 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
2aa80 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2aa90 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
2aaa0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f  ument to the BLO
2aab0 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e  B and string bin
2aac0 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a  ding interfaces.
2aad0 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ** is a destruct
2aae0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
2aaf0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2ab00 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
2ab10 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
2ab20 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
2ab30 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
2ab40 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
2ab50 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2ab60 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
2ab70 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
2ab80 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73  o bind API fails
2ab90 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2aba0 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
2abb0 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
2abc0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
2abd0 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
2abe0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2abf0 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
2ac00 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
2ac10 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
2ac20 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
2ac30 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
2ac40 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2ac50 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
2ac60 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
2ac70 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
2ac80 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
2ac90 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2aca0 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
2acb0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
2acc0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
2acd0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2ace0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
2acf0 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72  ** ^The sixth ar
2ad00 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2ad10 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2ad20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a  must be one of.*
2ad30 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  * [SQLITE_UTF8],
2ad40 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
2ad50 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2ad60 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
2ad70 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65  F16LE].** to spe
2ad80 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e  cify the encodin
2ad90 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e  g of the text in
2ada0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2adb0 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65  eter.  If.** the
2adc0 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2add0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2ade0 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20  text64() is not 
2adf0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c  one of the.** al
2ae00 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f  lowed values sho
2ae10 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20  wn above, or if 
2ae20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2ae30 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a  g is different.*
2ae40 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64  * from the encod
2ae50 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79  ing specified by
2ae60 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d   the sixth param
2ae70 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62  eter, then the b
2ae80 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
2ae90 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2aea0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2aeb0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
2aec0 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
2aed0 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
2aee0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
2aef0 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
2af00 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
2af10 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
2af20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
2af30 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
2af40 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
2af50 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
2af60 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
2af70 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
2af80 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
2af90 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2afa0 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
2afb0 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
2afc0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
2afd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2afe0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
2aff0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
2b000 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
2b010 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
2b020 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
2b030 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
2b040 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
2b050 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
2b060 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2b070 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
2b080 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
2b090 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
2b0a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2b0b0 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
2b0c0 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
2b0d0 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
2b0e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2b0f0 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
2b100 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
2b110 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
2b120 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
2b130 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
2b140 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2b150 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
2b160 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
2b170 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
2b180 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
2b190 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2b1a0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2b1b0 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
2b1c0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2b1d0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
2b1e0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
2b1f0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
2b200 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
2b210 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2b220 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
2b230 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
2b240 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
2b250 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
2b260 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2b270 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
2b280 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
2b290 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
2b2a0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
2b2b0 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
2b2c0 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
2b2d0 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68  ITE_TOOBIG] migh
2b2e0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66  t be returned if
2b2f0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73   the size of a s
2b300 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a  tring or BLOB.**
2b310 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20   exceeds limits 
2b320 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69  imposed by [sqli
2b330 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2b340 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2b350 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ) or.** [SQLITE_
2b360 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20  MAX_LENGTH]..** 
2b370 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
2b380 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
2b390 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2b3a0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2b3b0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
2b3c0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
2b3d0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
2b3e0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
2b3f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2b400 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2b410 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
2b420 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2b430 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2b440 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2b450 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2b460 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2b470 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2b480 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2b490 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2b4a0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2b4b0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
2b4c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2b4d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2b4e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2b4f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34  ite3_bind_blob64
2b500 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b510 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2b520 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2b530 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2b540 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2b550 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2b560 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2b570 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2b580 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
2b590 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2b5a0 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45   double);.SQLITE
2b5b0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2b5c0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2b5d0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
2b5e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2b5f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2b600 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2b610 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2b620 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2b630 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
2b640 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
2b650 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2b660 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2b670 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
2b680 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  stmt*, int);.SQL
2b690 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2b6a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2b6b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
2b6c0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63  ite3_stmt*,int,c
2b6d0 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76  onst char*,int,v
2b6e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2b6f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2b700 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2b710 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2b720 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2b730 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2b740 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2b750 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2b760 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2b770 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2b780 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ind_text64(sqlit
2b790 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2b7a0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
2b7b0 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
2b7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b7d0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2b7e0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68  d*), unsigned ch
2b7f0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51  ar encoding);.SQ
2b800 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2b810 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2b820 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
2b830 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b840 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
2b850 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2b860 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2b870 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2b880 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
2b890 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b8a0 2c 20 69 6e 74 20 6e 29 3b 0a 53 51 4c 49 54 45  , int n);.SQLITE
2b8b0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2b8c0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2b8d0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  bind_zeroblob64(
2b8e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b8f0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  nt, sqlite3_uint
2b900 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
2b910 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2b920 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
2b930 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2b940 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2b950 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2b960 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2b970 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2b980 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2b990 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2b9a0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2b9b0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2b9c0 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2b9d0 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2b9e0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2b9f0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2ba00 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2ba10 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2ba20 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2ba30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ba40 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2ba50 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2ba60 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2ba70 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2ba80 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2ba90 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2baa0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2bab0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2bac0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2bad0 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2bae0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2baf0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2bb00 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2bb10 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2bb20 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2bb30 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2bb40 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2bb50 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2bb60 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2bb70 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2bb80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2bb90 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2bba0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2bbb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2bbc0 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2bbd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2bbe0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2bbf0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2bc00 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2bc10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2bc20 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
2bc30 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2bc40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2bc50 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
2bc60 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f  rameter.** METHO
2bc70 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2bc80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bc90 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2bca0 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
2bcb0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
2bcc0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2bcd0 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
2bce0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
2bcf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bd00 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
2bd10 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2bd20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
2bd30 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2bd40 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
2bd50 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
2bd60 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
2bd70 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2bd80 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2bd90 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
2bda0 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
2bdb0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
2bdc0 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
2bdd0 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
2bde0 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
2bdf0 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
2be00 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
2be10 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
2be20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
2be30 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
2be40 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
2be50 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
2be60 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
2be70 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
2be80 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
2be90 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
2bea0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2beb0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
2bec0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
2bed0 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
2bee0 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
2bef0 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
2bf00 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
2bf10 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
2bf20 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
2bf30 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2bf40 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
2bf50 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
2bf60 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
2bf70 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
2bf80 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
2bf90 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
2bfa0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
2bfb0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
2bfc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bfd0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2bfe0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2bff0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2c000 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2c010 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2c020 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2c030 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2c040 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c050 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2c060 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2c070 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2c080 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2c090 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2c0a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c0b0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2c0c0 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2c0d0 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2c0e0 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20  A Given Name.** 
2c0f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2c100 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2c110 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
2c120 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
2c130 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
2c140 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
2c150 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
2c160 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
2c170 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
2c180 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2c190 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2c1a0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2c1b0 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
2c1c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2c1d0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
2c1e0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
2c1f0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
2c200 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
2c210 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
2c220 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
2c230 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
2c240 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
2c250 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
2c260 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2c270 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2c280 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2c290 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2c2a0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2c2b0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2c2c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2c2d0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2c2e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2c2f0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2c300 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2c310 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2c320 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  L sqlite3_bind_p
2c330 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2c340 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2c350 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2c360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c370 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2c380 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2c390 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2c3a0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2c3b0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  _stmt.**.** ^Con
2c3c0 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2c3d0 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2c3e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c3f0 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2c400 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2c410 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2c420 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2c430 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c440 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2c450 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2c460 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2c470 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2c480 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2c490 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2c4a0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2c4b0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2c4c0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2c4d0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2c4e0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
2c4f0 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
2c500 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2c510 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2c520 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2c530 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2c540 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
2c550 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
2c560 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
2c570 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2c580 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
2c590 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
2c5a0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
2c5b0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
2c5c0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
2c5d0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
2c5e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2c5f0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c600 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
2c610 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2c620 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2c630 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
2c640 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2c650 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c660 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
2c670 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
2c680 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2c690 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
2c6a0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2c6b0 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
2c6c0 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
2c6d0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
2c6e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2c6f0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
2c700 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
2c710 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2c720 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
2c730 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2c740 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2c750 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
2c760 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
2c770 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2c780 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
2c790 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2c7a0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
2c7b0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2c7c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2c7d0 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
2c7e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2c7f0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
2c800 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
2c810 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
2c820 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2c830 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
2c840 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
2c850 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2c860 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
2c870 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2c880 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
2c890 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
2c8a0 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
2c8b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2c8c0 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
2c8d0 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
2c8e0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2c8f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2c900 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2c910 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2c920 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
2c930 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2c940 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
2c950 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
2c960 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
2c970 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
2c980 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
2c990 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c9a0 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
2c9b0 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
2c9c0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
2c9d0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
2c9e0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
2c9f0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
2ca00 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
2ca10 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
2ca20 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
2ca30 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
2ca40 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
2ca50 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2ca60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
2ca70 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
2ca80 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
2ca90 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
2caa0 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
2cab0 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
2cac0 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
2cad0 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
2cae0 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
2caf0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
2cb00 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
2cb10 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
2cb20 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
2cb30 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
2cb40 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
2cb50 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45   next..*/.SQLITE
2cb60 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2cb70 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2cb80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2cb90 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2cba0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54  *, int N);.SQLIT
2cbb0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2cbc0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2cbd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cbe0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2cbf0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
2cc00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2cc10 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
2cc20 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2cc30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2cc40 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2cc50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
2cc60 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
2cc70 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
2cc80 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2cc90 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
2cca0 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
2ccb0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
2ccc0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
2ccd0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
2cce0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
2ccf0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2cd00 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
2cd10 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
2cd20 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
2cd30 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
2cd40 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
2cd50 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
2cd60 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
2cd70 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
2cd80 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
2cd90 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
2cda0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
2cdb0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
2cdc0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
2cdd0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2cde0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
2cdf0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2ce00 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
2ce10 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
2ce20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
2ce30 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
2ce40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2ce50 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2ce60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2ce70 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2ce80 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2ce90 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2cea0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2ceb0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2cec0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2ced0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
2cee0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
2cef0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
2cf00 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
2cf10 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
2cf20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
2cf30 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
2cf40 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
2cf50 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
2cf60 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2cf70 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
2cf80 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2cf90 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
2cfa0 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
2cfb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cfc0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
2cfd0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2cfe0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2cff0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
2d000 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2d010 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
2d020 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
2d030 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2d040 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2d050 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
2d060 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
2d070 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
2d080 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
2d090 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2d0a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2d0b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
2d0c0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
2d0d0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
2d0e0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
2d0f0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
2d100 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2d110 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
2d120 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
2d130 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
2d140 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
2d150 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2d160 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
2d170 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
2d180 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
2d190 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
2d1a0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
2d1b0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
2d1c0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
2d1d0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
2d1e0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
2d1f0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
2d200 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
2d210 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
2d220 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
2d230 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
2d240 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
2d250 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
2d260 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
2d270 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
2d280 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
2d290 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
2d2a0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
2d2b0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2d2c0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2d2d0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
2d2e0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
2d2f0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
2d300 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2d310 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2d320 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2d330 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2d340 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
2d350 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
2d360 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
2d370 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2d380 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2d390 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
2d3a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
2d3b0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2d3c0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2d3d0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
2d3e0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2d3f0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
2d400 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
2d410 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
2d420 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d430 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
2d440 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
2d450 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2d460 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2d470 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2d480 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d490 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
2d4a0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2d4b0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2d4c0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2d4d0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2d4e0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
2d4f0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2d500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2d510 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
2d520 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d530 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d540 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
2d550 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2d560 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2d570 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d580 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2d590 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
2d5a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d5b0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2d5c0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2d5d0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2d5e0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2d5f0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2d600 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
2d610 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
2d620 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2d630 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2d640 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
2d650 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2d660 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
2d670 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d680 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2d690 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
2d6a0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
2d6b0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
2d6c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2d6d0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  mt.**.** ^(The f
2d6e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2d6f0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2d700 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
2d710 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
2d720 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
2d730 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
2d740 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2d750 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
2d760 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
2d770 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
2d780 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
2d790 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2d7a0 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
2d7b0 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
2d7c0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
2d7d0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
2d7e0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
2d7f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2d800 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2d810 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
2d820 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2d830 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
2d840 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2d850 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
2d860 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
2d870 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
2d880 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2d890 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
2d8a0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2d8b0 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
2d8c0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
2d8d0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
2d8e0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2d8f0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2d900 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
2d910 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
2d920 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
2d930 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
2d940 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
2d950 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
2d960 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
2d970 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
2d980 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
2d990 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
2d9a0 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
2d9b0 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
2d9c0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
2d9d0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
2d9e0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
2d9f0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
2da00 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
2da10 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
2da20 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
2da30 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
2da40 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
2da50 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
2da60 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
2da70 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
2da80 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
2da90 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
2daa0 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
2dab0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
2dac0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
2dad0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2dae0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
2daf0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
2db00 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
2db10 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
2db20 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51  se values..*/.SQ
2db30 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2db40 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2db50 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2db60 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2db70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2db80 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2db90 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
2dba0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2dbb0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
2dbc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2dbd0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2dbe0 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
2dbf0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2dc00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2dc10 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74  3_stmt.**.** Aft
2dc20 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
2dc30 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
2dc40 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
2dc50 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
2dc60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2dc70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2dc80 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2dc90 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
2dca0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2dcb0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
2dcc0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
2dcd0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
2dce0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
2dcf0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2dd00 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2dd10 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
2dd20 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
2dd30 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
2dd40 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
2dd50 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
2dd60 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
2dd70 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
2dd80 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
2dd90 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
2dda0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
2ddb0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
2ddc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ddd0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2dde0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2ddf0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
2de00 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
2de10 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
2de20 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2de30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2de40 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
2de50 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
2de60 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
2de70 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
2de80 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
2de90 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
2dea0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
2deb0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
2dec0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
2ded0 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
2dee0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
2def0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
2df00 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
2df10 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
2df20 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
2df30 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
2df40 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
2df50 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
2df60 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
2df70 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
2df80 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
2df90 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
2dfa0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
2dfb0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
2dfc0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
2dfd0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
2dfe0 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
2dff0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
2e000 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
2e010 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
2e020 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
2e030 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
2e040 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
2e050 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2e060 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
2e070 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
2e080 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
2e090 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
2e0a0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
2e0b0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
2e0c0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
2e0d0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
2e0e0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
2e0f0 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
2e100 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2e110 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
2e120 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
2e130 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
2e140 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
2e150 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2e160 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
2e170 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
2e180 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
2e190 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
2e1a0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
2e1b0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2e1c0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2e1d0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
2e1e0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
2e1f0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
2e200 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2e210 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
2e220 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
2e230 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
2e240 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
2e250 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
2e260 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
2e270 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
2e280 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
2e290 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
2e2a0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
2e2b0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
2e2c0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
2e2d0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
2e2e0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
2e2f0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
2e300 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
2e310 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
2e320 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2e330 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
2e340 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
2e350 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
2e360 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
2e370 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
2e380 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
2e390 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
2e3a0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
2e3b0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
2e3c0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
2e3d0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
2e3e0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2e3f0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2e400 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
2e410 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
2e420 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
2e430 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
2e440 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2e450 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2e460 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2e470 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
2e480 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
2e490 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
2e4a0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
2e4b0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
2e4c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
2e4d0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
2e4e0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
2e4f0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
2e500 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e510 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
2e520 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e530 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
2e540 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
2e550 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2e560 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
2e570 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2e580 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2e590 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
2e5a0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
2e5b0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
2e5c0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
2e5d0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
2e5e0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
2e5f0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
2e600 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e610 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
2e620 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
2e630 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2e640 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
2e650 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
2e660 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
2e670 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
2e680 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
2e690 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
2e6a0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
2e6b0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
2e6c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2e6d0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
2e6e0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
2e6f0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
2e700 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
2e710 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
2e720 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
2e730 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
2e740 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
2e750 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
2e760 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
2e770 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
2e780 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
2e790 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
2e7a0 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
2e7b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2e7c0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
2e7d0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
2e7e0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
2e7f0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
2e800 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
2e810 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2e820 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
2e830 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e840 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
2e850 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
2e860 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
2e870 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
2e880 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
2e890 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
2e8a0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
2e8b0 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
2e8c0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2e8d0 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
2e8e0 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
2e8f0 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
2e900 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
2e910 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2e920 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
2e930 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
2e940 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
2e950 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
2e960 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
2e970 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
2e980 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
2e990 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
2e9a0 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
2e9b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
2e9c0 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
2e9d0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2e9e0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
2e9f0 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
2ea00 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
2ea10 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
2ea20 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
2ea30 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
2ea40 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2ea50 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
2ea60 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
2ea70 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
2ea80 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
2ea90 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
2eaa0 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
2eab0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
2eac0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
2ead0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2eae0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
2eaf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2eb00 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2eb10 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
2eb20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
2eb30 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
2eb40 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2eb50 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
2eb60 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
2eb70 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
2eb80 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
2eb90 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
2eba0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
2ebb0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
2ebc0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2ebd0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
2ebe0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
2ebf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
2ec00 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
2ec10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ec20 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2ec30 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2ec40 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
2ec50 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
2ec60 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2ec70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2ec80 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
2ec90 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
2eca0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2ecb0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
2ecc0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
2ecd0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
2ece0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
2ecf0 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
2ed00 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2ed10 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  mmended..*/.SQLI
2ed20 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2ed30 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2ed40 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2ed50 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2ed60 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2ed70 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2ed80 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54  esult set.** MET
2ed90 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2eda0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2edb0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2edc0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2edd0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2ede0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2edf0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
2ee00 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2ee10 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
2ee20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2ee30 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
2ee40 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
2ee50 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
2ee60 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
2ee70 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
2ee80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2ee90 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
2eea0 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
2eeb0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
2eec0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
2eed0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
2eee0 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
2eef0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2ef00 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
2ef10 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
2ef20 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2ef30 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
2ef40 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2ef50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2ef60 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
2ef70 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
2ef80 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2ef90 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2efa0 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
2efb0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2efc0 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
2efd0 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
2efe0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2eff0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2f000 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
2f010 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
2f020 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
2f030 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
2f040 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
2f050 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
2f060 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
2f070 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
2f080 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
2f090 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
2f0a0 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
2f0b0 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
2f0c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2f0d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2f0e0 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
2f0f0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2f100 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 64 61 74  CALL sqlite3_dat
2f110 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
2f120 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2f130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2f140 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
2f150 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
2f160 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
2f170 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
2f180 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2f190 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2f1a0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2f1b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2f1c0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2f1d0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2f1e0 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2f1f0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2f200 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2f210 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2f220 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2f230 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
2f240 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2f250 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
2f260 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
2f270 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2f280 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
2f290 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
2f2a0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
2f2b0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
2f2c0 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
2f2d0 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
2f2e0 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
2f2f0 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
2f300 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
2f310 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
2f320 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
2f330 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
2f340 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
2f350 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
2f360 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2f370 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
2f380 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
2f390 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2f3a0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
2f3b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
2f3c0 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
2f3d0 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
2f3e0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2f3f0 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
2f400 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
2f410 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
2f420 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
2f430 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
2f440 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
2f450 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
2f460 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
2f470 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2f480 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
2f490 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2f4a0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2f4b0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2f4c0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2f4d0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2f4e0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2f4f0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2f500 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2f510 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2f520 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2f530 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2f540 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f550 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2f560 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2f570 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2f580 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2f590 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
2f5a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2f5b0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
2f5c0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
2f5d0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2f5e0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2f5f0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2f600 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
2f610 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
2f620 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
2f630 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2f640 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2f650 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
2f660 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
2f670 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2f680 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
2f690 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
2f6a0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2f6b0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2f6c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2f6d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
2f6e0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
2f6f0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
2f700 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
2f710 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
2f720 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
2f730 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
2f740 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
2f750 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
2f760 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2f770 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
2f780 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2f790 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f7a0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
2f7b0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
2f7c0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2f7d0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
2f7e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f7f0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
2f800 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
2f810 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
2f820 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2f830 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
2f840 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2f850 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2f860 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2f870 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
2f880 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2f890 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
2f8a0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2f8b0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
2f8c0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2f8d0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
2f8e0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2f8f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f900 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2f910 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
2f920 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
2f930 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
2f940 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
2f950 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2f960 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
2f970 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2f980 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2f990 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2f9a0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
2f9b0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
2f9c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
2f9d0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
2f9e0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
2f9f0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
2fa00 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
2fa10 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
2fa20 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
2fa30 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2fa40 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
2fa50 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
2fa60 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
2fa70 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
2fa80 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
2fa90 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
2faa0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2fab0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
2fac0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
2fad0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
2fae0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
2faf0 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
2fb00 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
2fb10 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2fb20 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
2fb30 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2fb40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2fb50 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
2fb60 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
2fb70 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
2fb80 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
2fb90 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2fba0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
2fbb0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
2fbc0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
2fbd0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2fbe0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2fbf0 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
2fc00 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2fc10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2fc20 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2fc30 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2fc40 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2fc50 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2fc60 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2fc70 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2fc80 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2fc90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2fca0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2fcb0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2fcc0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2fcd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2fce0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2fcf0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2fd00 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2fd10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fd20 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
2fd30 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2fd40 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2fd50 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2fd60 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
2fd70 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2fd80 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2fd90 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2fda0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2fdb0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2fdc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2fdd0 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
2fde0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
2fdf0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2fe00 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
2fe10 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2fe20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fe30 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
2fe40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2fe50 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2fe60 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2fe70 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2fe80 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2fe90 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
2fea0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2feb0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
2fec0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2fed0 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
2fee0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2fef0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2ff00 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2ff10 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2ff20 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2ff30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ff40 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2ff50 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2ff60 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2ff70 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
2ff80 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2ff90 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2ffa0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2ffb0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2ffc0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2ffd0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2ffe0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fff0 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
30000 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
30010 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
30020 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
30030 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
30040 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
30050 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
30060 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
30070 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
30080 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
30090 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
300a0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
300b0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
300c0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
300d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
300e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
300f0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
30100 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
30110 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
30120 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
30130 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
30140 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
30150 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
30160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30170 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
30180 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30190 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
301a0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
301b0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
301c0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
301d0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
301e0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
301f0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
30200 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
30210 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
30220 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69  ..**.** <b>Warni
30230 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a  ng:</b> ^The obj
30240 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
30250 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
30260 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
30270 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
30280 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30290 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74  ject.  In a mult
302a0 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f  ithreaded enviro
302b0 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70  nment,.** an unp
302c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
302d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
302e0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73  y only be used s
302f0 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73  afely with.** [s
30300 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
30310 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
30320 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
30330 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
30340 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30350 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30360 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
30370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
30380 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
30390 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
303a0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
303b0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
303c0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
303d0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
303e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
303f0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
30400 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
30410 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  )], the behavior
30420 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
30430 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  fe..**.** These 
30440 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
30450 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
30460 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
30470 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
30480 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
30490 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
304a0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
304b0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
304c0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
304d0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
304e0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
304f0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
30500 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
30510 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
30520 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
30530 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
30540 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
30550 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
30560 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
30570 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
30580 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
30590 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
305a0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
305b0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
305c0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
305d0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
305e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
305f0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
30600 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
30610 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
30620 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
30630 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
30640 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
30650 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
30660 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
30670 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
30680 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
30690 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
306a0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
306b0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
306c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
306d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
306e0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
306f0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
30700 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
30710 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
30720 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
30730 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
30740 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
30750 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
30760 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
30770 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
30780 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
30790 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
307a0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
307b0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
307c0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
307d0 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
307e0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
307f0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
30800 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
30810 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
30820 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
30830 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
30840 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
30850 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
30860 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
30870 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
30880 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
30890 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
308a0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
308b0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
308c0 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
308d0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
308e0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
308f0 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
30900 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
30910 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
30920 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
30930 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
30940 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
30950 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
30960 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
30970 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
30980 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
30990 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
309a0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
309b0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
309c0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
309d0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ote>)^.**.** Not
309e0 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
309f0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
30a00 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
30a10 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
30a20 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
30a30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
30a40 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
30a50 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
30a60 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
30a70 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
30a80 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
30a90 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
30aa0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
30ab0 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
30ac0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
30ad0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
30ae0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
30af0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
30b00 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
30b10 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
30b20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
30b30 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
30b40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
30b50 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
30b60 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
30b70 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
30b80 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
30b90 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
30ba0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
30bb0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
30bc0 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
30bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30be0 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
30bf0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
30c00 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
30c10 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
30c20 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
30c30 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
30c40 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
30c50 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
30c60 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
30c70 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
30c80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30c90 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
30ca0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30cb0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
30cc0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
30cd0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
30ce0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
30cf0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
30d00 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
30d10 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
30d20 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
30d30 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
30d40 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
30d50 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
30d60 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
30d70 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
30d80 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
30d90 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
30da0 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
30db0 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
30dc0 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
30dd0 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
30de0 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
30df0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
30e00 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
30e10 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
30e20 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
30e30 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
30e40 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
30e50 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
30e60 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
30e70 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
30e80 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c  * The safest pol
30e90 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
30ea0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
30eb0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
30ec0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
30ed0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
30ee0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
30ef0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
30f00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
30f10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
30f20 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
30f30 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
30f40 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
30f50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30f60 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
30f70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30f80 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
30f90 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
30fa0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
30fb0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
30fc0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
30fd0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
30fe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30ff0 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
31000 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
31010 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
31020 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
31030 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
31040 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
31050 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
31060 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
31070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31080 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
31090 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
310a0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
310b0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
310c0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
310d0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
310e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
310f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
31100 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
31110 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
31120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31130 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
31140 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
31150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
31160 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
31170 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
31180 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
31190 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
311a0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
311b0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
311c0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
311d0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
311e0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
311f0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
31200 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
31210 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
31220 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
31230 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
31240 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
31250 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
31260 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
31270 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
31280 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
31290 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  Do <em>not</em> 
312a0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
312b0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
312c0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
312d0 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
312e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
312f0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
31300 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
31310 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
31320 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
31330 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
31340 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
31350 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
31360 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
31370 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
31380 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
31390 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
313a0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
313b0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
313c0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
313d0 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
313e0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
313f0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
31400 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
31410 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
31420 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
31430 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
31440 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31450 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
31460 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
31470 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
31480 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31490 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
314a0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
314b0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
314c0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
314d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
314e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
314f0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
31500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31510 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
31520 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31530 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
31540 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  le SQLITE_STDCAL
31550 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
31560 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
31570 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
31580 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
31590 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
315a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
315b0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
315c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
315d0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
315e0 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
315f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
31600 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
31610 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31620 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
31630 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
31640 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
31650 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
31660 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
31670 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31680 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31690 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
316a0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
316b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
316c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
316d0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
316e0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
316f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
31700 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
31710 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31720 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
31730 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c  lite3_value *SQL
31740 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
31750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
31760 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31770 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
31780 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
31790 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
317a0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
317b0 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
317c0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
317d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
317e0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
317f0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
31800 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
31810 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
31820 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
31830 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
31840 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
31850 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
31860 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
31870 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
31880 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
31890 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
318a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
318b0 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
318c0 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
318d0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
318e0 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
318f0 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
31900 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
31910 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
31920 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
31930 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
31940 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
31950 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
31960 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
31970 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
31980 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
31990 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
319a0 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
319b0 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
319c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
319d0 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
319e0 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
319f0 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
31a00 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
31a10 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
31a20 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
31a30 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
31a40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
31a50 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
31a60 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
31a70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
31a80 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
31a90 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
31aa0 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
31ab0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
31ac0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
31ad0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
31ae0 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
31af0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
31b00 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
31b10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31b20 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
31b30 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
31b40 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
31b50 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
31b60 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
31b70 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
31b80 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
31b90 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
31ba0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
31bb0 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
31bc0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
31bd0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
31be0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
31bf0 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
31c00 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
31c10 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
31c20 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
31c30 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
31c40 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
31c50 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
31c60 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
31c70 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ALL sqlite3_fina
31c80 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
31c90 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
31ca0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
31cb0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
31cc0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
31cd0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31ce0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  _stmt.**.** The 
31cf0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
31d00 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
31d10 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
31d20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31d30 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
31d40 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
31d50 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
31d60 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
31d70 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
31d80 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
31d90 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
31da0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
31db0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
31dc0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
31dd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
31de0 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
31df0 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
31e00 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
31e10 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
31e20 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
31e30 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
31e40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
31e50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
31e60 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
31e70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
31e80 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
31e90 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
31ea0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
31eb0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
31ec0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
31ed0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
31ee0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
31ef0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
31f00 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
31f10 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
31f20 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
31f30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
31f40 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
31f50 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
31f60 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
31f70 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
31f80 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
31f90 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
31fa0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
31fb0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
31fc0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
31fd0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
31fe0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
31ff0 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
32000 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
32010 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
32020 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
32030 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
32040 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
32050 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
32060 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
32070 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
32080 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
32090 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
320a0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
320b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
320c0 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nt] S..*/.SQLITE
320d0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
320e0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
320f0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
32100 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
32110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
32120 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
32130 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
32140 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
32150 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
32160 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
32170 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
32180 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
32190 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
321a0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
321b0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
321c0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
321d0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
321e0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
321f0 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
32200 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
32210 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
32220 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
32230 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
32240 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
32250 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
32260 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
32270 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
32280 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
32290 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
322a0 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
322b0 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
322c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
322d0 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
322e0 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
322f0 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
32300 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
32310 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
32320 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
32330 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
32340 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
32350 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
32360 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
32370 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
32380 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
32390 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
323a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
323b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
323c0 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
323d0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
323e0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
323f0 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
32400 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
32410 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
32420 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
32430 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
32440 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
32450 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
32460 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
32470 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
32480 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
32490 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
324a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
324b0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
324c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
324d0 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
324e0 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
324f0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
32500 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
32510 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
32520 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
32530 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
32540 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
32550 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
32560 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
32570 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
32580 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
32590 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
325a0 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
325b0 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
325c0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
325d0 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
325e0 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
325f0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
32600 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
32610 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
32620 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
32630 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
32640 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
32650 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
32660 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
32670 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
32680 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
32690 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
326a0 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
326b0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
326c0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
326d0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
326e0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
326f0 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
32700 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
32710 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
32720 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
32730 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
32740 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
32750 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
32760 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
32770 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
32780 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
32790 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
327a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
327b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
327c0 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
327d0 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
327e0 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
327f0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
32800 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
32810 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
32820 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65  parameters.  The
32830 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
32840 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72  uld set this par
32850 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51  ameter to.** [SQ
32860 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66  LITE_UTF16LE] if
32870 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
32880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
32890 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  okes .** [sqlite
328a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
328b0 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
328c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
328d0 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69  6BE] if the.** i
328e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
328f0 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76  vokes [sqlite3_v
32900 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d  alue_text16be()]
32910 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
32920 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
32930 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76  6] if [sqlite3_v
32940 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69  alue_text16()] i
32950 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49  s used, or [SQLI
32960 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65  TE_UTF8].** othe
32970 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d  rwise.  ^The sam
32980 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d  e SQL function m
32990 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
329a0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
329b0 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65  using.** differe
329c0 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78  nt preferred tex
329d0 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74  t encodings, wit
329e0 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c  h different impl
329f0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a  ementations for.
32a00 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67  ** each encoding
32a10 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
32a20 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
32a30 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
32a40 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
32a50 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
32a60 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
32a70 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
32a80 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
32a90 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
32aa0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rsion..**.** ^Th
32ab0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
32ac0 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  er may optionall
32ad0 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b  y be ORed with [
32ae0 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
32af0 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e  STIC].** to sign
32b00 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63  al that the func
32b10 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73  tion will always
32b20 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
32b30 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a   result given.**
32b40 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
32b50 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65   within a single
32b60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
32b70 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69   Most SQL functi
32b80 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72  ons are.** deter
32b90 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62  ministic.  The b
32ba0 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28  uilt-in [random(
32bb0 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  )] SQL function 
32bc0 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
32bd0 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74   a.** function t
32be0 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72  hat is not deter
32bf0 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53  ministic.  The S
32c00 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e  QLite query plan
32c10 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  ner is able to.*
32c20 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69  * perform additi
32c30 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f  onal optimizatio
32c40 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73  ns on determinis
32c50 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73  tic functions, s
32c60 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20  o use.** of the 
32c70 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
32c80 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72  ISTIC] flag is r
32c90 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65  ecommended where
32ca0 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a   possible..**.**
32cb0 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
32cc0 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
32cd0 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
32ce0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
32cf0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
32d00 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
32d10 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
32d20 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
32d30 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
32d40 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
32d50 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
32d60 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
32d70 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
32d80 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
32d90 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
32da0 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
32db0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
32dc0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
32dd0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
32de0 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
32df0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
32e00 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
32e10 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
32e20 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
32e30 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
32e40 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
32e50 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
32e60 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
32e70 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
32e80 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
32e90 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
32ea0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
32eb0 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
32ec0 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
32ed0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
32ee0 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
32ef0 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
32f00 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
32f10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
32f20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
32f30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
32f40 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
32f50 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
32f60 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
32f70 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
32f80 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
32f90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
32fa0 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
32fb0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
32fc0 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
32fd0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32fe0 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
32ff0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
33000 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
33010 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
33020 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
33030 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
33040 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
33050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33060 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
33070 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
33080 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
33090 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
330a0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
330b0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
330c0 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
330d0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
330e0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
330f0 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
33100 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
33110 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
33120 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
33130 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
33140 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33150 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
33160 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
33170 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
33180 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
33190 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
331a0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
331b0 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
331c0 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
331d0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
331e0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
331f0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
33200 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
33210 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
33220 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
33230 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
33240 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
33250 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
33260 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
33270 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
33280 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
33290 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
332a0 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
332b0 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
332c0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
332d0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
332e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
332f0 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
33300 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
33310 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
33320 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
33330 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
33340 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
33350 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
33360 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
33370 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
33380 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
33390 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
333a0 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
333b0 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
333c0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
333d0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
333e0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
333f0 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
33400 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
33410 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
33420 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
33430 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
33440 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
33450 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
33460 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
33470 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
33480 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
33490 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
334a0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
334b0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
334c0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
334d0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
334e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
334f0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
33500 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33510 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
33520 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
33530 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
33540 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
33550 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
33560 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
33570 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
33580 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
33590 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
335a0 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
335b0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
335c0 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
335d0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
335e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
335f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33600 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33610 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
33620 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
33630 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
33640 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
33650 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
33660 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
33670 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
33680 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
33690 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
336a0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
336b0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
336c0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
336d0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
336e0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
336f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
33700 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33710 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
33720 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33730 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
33740 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
33750 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
33760 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
33770 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
33780 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
33790 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
337a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
337b0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
337c0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
337d0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
337e0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
337f0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33800 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
33810 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
33820 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
33830 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
33840 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  L sqlite3_create
33850 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
33860 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
33870 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
33880 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
33890 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
338a0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
338b0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
338c0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
338d0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
338e0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
338f0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
33900 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33920 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
33930 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
33940 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
33950 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
33960 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33970 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
33980 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
33990 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
339a0 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
339b0 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
339c0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
339d0 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
339e0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
339f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33a00 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
33a10 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37      /* IMP: R-37
33a20 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65  514-35566 */.#de
33a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
33a40 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20  6LE        2    
33a50 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d  /* IMP: R-03371-
33a60 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65  37637 */.#define
33a70 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
33a80 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49         3    /* I
33a90 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35  MP: R-51971-3415
33aa0 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
33ab0 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
33ac0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
33ad0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
33ae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
33af0 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
33b00 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63    5    /* Deprec
33b10 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ated */.#define 
33b20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
33b30 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
33b40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33b50 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
33b60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33b70 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a  Function Flags.*
33b80 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
33b90 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64  ants may be ORed
33ba0 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74   together with t
33bb0 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  he .** [SQLITE_U
33bc0 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20  TF8 | preferred 
33bd0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61  text encoding] a
33be0 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
33bf0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ument.** to [sql
33c00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33c10 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
33c20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33c30 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
33c40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33c50 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  nction_v2()]..*/
33c60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33c70 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20  DETERMINISTIC   
33c80 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41   0x800../*.** CA
33c90 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
33ca0 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
33cb0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
33cc0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
33cd0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
33ce0 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
33cf0 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
33d00 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
33d10 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
33d20 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
33d30 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
33d40 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
33d50 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
33d60 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
33d70 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
33d80 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
33d90 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e  unctions.  To en
33da0 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d  courage programm
33db0 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ers to avoid.** 
33dc0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
33dd0 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70   we will not exp
33de0 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64  lain what they d
33df0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
33e00 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
33e10 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20  ATED.SQLITE_API 
33e20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
33e30 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  D int SQLITE_STD
33e40 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 67  CALL sqlite3_agg
33e50 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
33e60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
33e70 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
33e80 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
33e90 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
33ea0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
33eb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
33ec0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
33ed0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
33ee0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
33ef0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
33f00 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
33f10 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
33f20 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
33f30 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
33f40 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
33f50 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33f60 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
33f70 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
33f80 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
33f90 54 45 44 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  TED void SQLITE_
33fa0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33fb0 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
33fc0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
33fd0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
33fe0 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  ED int SQLITE_ST
33ff0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65  DCALL sqlite3_me
34000 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
34010 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
34020 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20  _int64,int),.   
34030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34040 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33     void*,sqlite3
34050 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
34060 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34070 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56   Obtaining SQL V
34080 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
34090 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
340a0 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
340b0 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
340c0 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
340d0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
340e0 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
340f0 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
34100 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
34110 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
34120 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
34130 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
34140 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a  ggregate.  .**.*
34150 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
34160 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
34170 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
34180 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
34190 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
341a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
341b0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
341c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
341d0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
341e0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
341f0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
34200 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
34210 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
34220 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
34230 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
34240 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
34250 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
34260 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
34270 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34280 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
34290 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
342a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
342b0 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
342c0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
342d0 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
342e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
342f0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
34300 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
34310 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34320 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
34330 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
34340 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
34350 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34360 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
34370 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
34380 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
34390 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
343a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
343b0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
343c0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
343d0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
343e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
343f0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
34400 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
34410 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
34420 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
34430 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
34440 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
34450 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
34460 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34470 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
34480 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
34490 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
344a0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
344b0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
344c0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
344d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
344e0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
344f0 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
34500 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
34510 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
34520 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
34530 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
34540 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
34550 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34560 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
34570 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
34580 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
34590 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
345a0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
345b0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
345c0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
345d0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
345e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
345f0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
34600 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
34610 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
34620 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
34630 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
34640 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
34650 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
34660 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
34670 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
34680 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
34690 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
346a0 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
346b0 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
346c0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
346d0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
346e0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
346f0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
34700 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
34710 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
34720 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
34730 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
34740 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
34750 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
34760 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
34770 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
34780 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
34790 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
347a0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
347b0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
347c0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
347d0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
347e0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
347f0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
34800 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
34810 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
34820 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
34830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
34840 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
34850 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
34860 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
34870 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
34880 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
34890 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
348a0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
348b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
348c0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
348d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
348e0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
348f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
34900 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
34910 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
34920 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
34930 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
34940 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
34950 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
34960 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ters..*/.SQLITE_
34970 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
34980 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
34990 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
349a0 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
349b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
349c0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
349d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
349e0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
349f0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34a00 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
34a10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
34a20 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
34a30 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34a40 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c  E_API double SQL
34a50 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34a60 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
34a70 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34a80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
34a90 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
34aa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
34ab0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
34ac0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
34ad0 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49  lite3_int64 SQLI
34ae0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
34af0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
34b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34b10 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
34b20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
34b30 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
34b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34b50 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
34b60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
34b70 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
34b80 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34b90 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
34ba0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34bb0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
34bc0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
34bd0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
34be0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
34bf0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
34c00 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
34c10 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
34c20 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
34c30 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
34c40 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34c50 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
34c60 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34c70 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
34c80 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
34c90 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
34ca0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
34cb0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
34cc0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
34cd0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
34ce0 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64  PI3REF: Copy And
34cf0 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73   Free SQL Values
34d00 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
34d10 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
34d20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
34d30 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66  ue_dup(V) interf
34d40 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
34d50 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
34d60 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
34d70 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20  t D and returns 
34d80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
34d90 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73  t copy.  ^The [s
34da0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65  qlite3_value] re
34db0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b  turned.** is a [
34dc0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
34dd0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
34de0 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75  even if the inpu
34df0 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68  t is not..** ^Th
34e00 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
34e10 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65  dup(V) interface
34e20 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
34e30 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66   V is NULL or if
34e40 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
34e50 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a  ocation fails..*
34e60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34e70 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20  3_value_free(V) 
34e80 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20  interface frees 
34e90 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  an [sqlite3_valu
34ea0 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65  e] object.** pre
34eb0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
34ec0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
34ed0 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49  alue_dup()].  ^I
34ee0 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f V is a NULL po
34ef0 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71  inter.** then sq
34f00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
34f10 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73  (V) is a harmles
34f20 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49  s no-op..*/.SQLI
34f30 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
34f40 50 45 52 49 4d 45 4e 54 41 4c 20 73 71 6c 69 74  PERIMENTAL sqlit
34f50 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45  e3_value *SQLITE
34f60 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34f70 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74  _value_dup(const
34f80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
34f90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
34fa0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
34fb0 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44   void SQLITE_STD
34fc0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
34fd0 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ue_free(sqlite3_
34fe0 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
34ff0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
35000 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
35010 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d  ion Context.** M
35020 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
35030 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
35040 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
35050 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
35060 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
35070 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
35080 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
35090 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
350a0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
350b0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
350c0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
350d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
350e0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
350f0 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
35100 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
35110 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
35120 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
35130 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
35140 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
35150 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
35160 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
35170 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
35180 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
35190 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
351a0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
351b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
351c0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
351d0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
351e0 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
351f0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
35200 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
35210 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
35220 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
35230 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
35240 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
35250 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
35260 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
35270 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
35280 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
35290 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
352a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
352b0 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
352c0 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
352d0 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
352e0 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
352f0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
35300 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
35310 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
35320 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
35330 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
35340 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
35350 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
35360 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
35370 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
35380 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
35390 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
353a0 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
353b0 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
353c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
353d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
353e0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
353f0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
35400 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20  ointer .** when 
35410 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20  first called if 
35420 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
35430 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
35440 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a  or if a memory.*
35450 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72  * allocate error
35460 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e   occurs..**.** ^
35470 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73  (The amount of s
35480 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  pace allocated b
35490 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  y sqlite3_aggreg
354a0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
354b0 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65   is.** determine
354c0 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d  d by the N param
354d0 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75  eter on first su
354e0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20  ccessful call.  
354f0 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20  Changing the.** 
35500 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75  value of N in su
35510 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
35520 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
35530 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74  te_context() wit
35540 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  hin.** the same 
35550 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
35560 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c  on instance will
35570 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20   not resize the 
35580 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
35590 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20  tion.)^  Within 
355a0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
355b0 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f  ack, it is custo
355c0 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e  mary to set.** N
355d0 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73  =0 in calls to s
355e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
355f0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f  _context(C,N) so
35600 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69   that no .** poi
35610 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c  ntless memory al
35620 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e  locations occur.
35630 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
35640 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
35650 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
35660 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
35670 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
35680 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
35690 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
356a0 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
356b0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
356c0 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
356d0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
356e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
356f0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
35700 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
35710 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
35720 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
35730 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
35740 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
35750 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
35760 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
35770 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
35780 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
35790 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
357a0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
357b0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
357c0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
357d0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
357e0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
357f0 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
35800 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
35810 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35820 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
35830 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
35840 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35850 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
35860 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  r Functions.** M
35870 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
35880 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  ontext.**.** ^Th
35890 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
358a0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
358b0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
358c0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
358d0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
358e0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
358f0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
35900 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
35910 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35920 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
35930 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
35940 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
35950 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
35960 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
35970 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
35980 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
35990 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
359a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
359b0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
359c0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
359d0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
359e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
359f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
35a00 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
35a10 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
35a20 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
35a30 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
35a40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35a50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35a60 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
35a70 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
35a80 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
35a90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
35aa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35ab0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
35ac0 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
35ad0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
35ae0 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
35af0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
35b00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
35b10 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
35b20 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
35b30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35b40 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
35b50 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35b60 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
35b70 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
35b80 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
35b90 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
35ba0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
35bb0 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ction..*/.SQLITE
35bc0 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 53 51  _API sqlite3 *SQ
35bd0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
35be0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
35bf0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
35c00 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
35c10 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
35c20 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
35c30 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ta.** METHOD: sq
35c40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
35c50 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
35c60 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
35c70 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74  by (non-aggregat
35c80 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  e) SQL functions
35c90 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
35ca0 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
35cb0 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
35cc0 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
35cd0 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
35ce0 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
35cf0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
35d00 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
35d10 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
35d20 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
35d30 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
35d40 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
35d50 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
35d60 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41  be preserved.  A
35d70 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20  n example.** of 
35d80 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74  where this might
35d90 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e   be useful is in
35da0 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
35db0 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a  ssion matching.*
35dc0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
35dd0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
35de0 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
35df0 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
35e00 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  e stored as.** m
35e10 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
35e20 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74  ed with the patt
35e30 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a  ern string.  .**
35e40 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73   Then as long as
35e50 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72   the pattern str
35e60 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20  ing remains the 
35e70 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d  same,.** the com
35e80 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
35e90 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
35ea0 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
35eb0 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
35ec0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
35ed0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nction..**.** ^T
35ee0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
35ef0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
35f00 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
35f10 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
35f20 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
35f30 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
35f40 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
35f50 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
35f60 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
35f70 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
35f80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35f90 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66  ed function. ^If
35fa0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74   there is no met
35fb0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
35fc0 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e  ted with the fun
35fd0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20  ction argument, 
35fe0 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74  this sqlite3_get
35ff0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
36000 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  face.** returns 
36010 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
36020 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36030 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
36040 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63  ,N,P,X) interfac
36050 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74  e saves P as met
36060 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
36070 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
36080 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
36090 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
360a0 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74  on.  ^Subsequent
360b0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
360c0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
360d0 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66  (C,N) return P f
360e0 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63  rom the most rec
360f0 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ent.** sqlite3_s
36100 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
36110 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20  ,X) call if the 
36120 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c  metadata is stil
36130 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55  l valid or.** NU
36140 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61  LL if the metada
36150 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63  ta has been disc
36160 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72  arded..** ^After
36170 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   each call to sq
36180 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
36190 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65  a(C,N,P,X) where
361a0 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a   X is not NULL,.
361b0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  ** SQLite will i
361c0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
361d0 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20  ctor function X 
361e0 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50  with parameter P
361f0 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65   exactly.** once
36200 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64  , when the metad
36210 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64  ata is discarded
36220 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  ..** SQLite is f
36230 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74  ree to discard t
36240 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61  he metadata at a
36250 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69  ny time, includi
36260 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  ng: <ul>.** <li>
36270 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
36280 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
36290 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
362a0 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77  es, or.** <li> w
362b0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
362c0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
362d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
362e0 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
362f0 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74  **      SQL stat
36300 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  ement, or.** <li
36310 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  > when sqlite3_s
36320 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20  et_auxdata() is 
36330 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e  invoked again on
36340 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65   the same parame
36350 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ter, or.** <li> 
36360 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69  during the origi
36370 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  nal sqlite3_set_
36380 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77  auxdata() call w
36390 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a  hen a memory .**
363a0 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e        allocation
363b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c   error occurs. <
363c0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  /ul>)^.**.** Not
363d0 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65  e the last bulle
363e0 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e  t in particular.
363f0 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72    The destructor
36400 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65   X in .** sqlite
36410 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
36420 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20  N,P,X) might be 
36430 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65  called immediate
36440 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a  ly, before the.*
36450 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
36460 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
36470 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20  e even returns. 
36480 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73   Hence sqlite3_s
36490 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20  et_auxdata().** 
364a0 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64  should be called
364b0 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66   near the end of
364c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
364d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  plementation and
364e0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
364f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36500 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20  should not make 
36510 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 74  any use of P aft
36520 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  er.** sqlite3_se
36530 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 20  t_auxdata() has 
36540 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a  been called..**.
36550 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
36560 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
36570 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
36580 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
36590 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  or.** function p
365a0 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
365b0 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  re compile-time 
365c0 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75  constants, inclu
365d0 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  ding literal.** 
365e0 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
365f0 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72  meters] and expr
36600 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64  essions composed
36610 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29   from the same.)
36620 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
36630 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
36640 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
36650 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
36660 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
36670 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
36680 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
36690 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  I void *SQLITE_S
366a0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67  TDCALL sqlite3_g
366b0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
366c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
366d0 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20   N);.SQLITE_API 
366e0 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
366f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  ALL sqlite3_set_
36700 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
36710 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
36720 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
36730 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
36740 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
36750 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
36760 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
36770 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
36780 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
36790 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
367a0 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
367b0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
367c0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
367d0 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
367e0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
367f0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
36800 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
36810 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
36820 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
36830 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
36840 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
36850 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
36860 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
36870 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
36880 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
36890 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
368a0 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
368b0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
368c0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
368d0 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
368e0 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
368f0 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
36900 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
36910 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
36920 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
36930 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
36940 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
36950 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
36960 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
36970 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
36980 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
36990 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
369a0 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64  pilers..*/.typed
369b0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
369c0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
369d0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
369e0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
369f0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
36a00 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
36a10 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
36a20 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
36a30 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
36a40 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
36a50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
36a60 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
36a70 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
36a80 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  on.** METHOD: sq
36a90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
36aa0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
36ab0 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
36ac0 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
36ad0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
36ae0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
36af0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
36b00 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
36b10 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
36b20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36b30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
36b40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
36b50 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
36b60 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
36b70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
36b80 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
36b90 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
36ba0 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
36bb0 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
36bc0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
36bd0 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
36be0 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
36bf0 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
36c00 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
36c10 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
36c20 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
36c30 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
36c40 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
36c50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
36c60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36c70 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
36c80 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
36c90 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
36ca0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36cb0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
36cc0 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
36cd0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
36ce0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
36cf0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
36d00 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
36d10 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
36d20 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
36d30 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
36d40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36d50 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e  ult_zeroblob(C,N
36d60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
36d70 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  sult_zeroblob64(
36d80 43 2c 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  C,N).** interfac
36d90 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
36da0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
36db0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36dc0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
36dd0 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
36de0 20 61 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73 20   all zero bytes 
36df0 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
36e00 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ize..**.** ^The 
36e10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
36e20 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
36e30 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
36e40 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
36e50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36e60 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36e70 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
36e80 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
36e90 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
36ea0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
36eb0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36ec0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
36ed0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36ee0 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
36ef0 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
36f00 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
36f10 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
36f20 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
36f30 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
36f40 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
36f50 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
36f60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
36f70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36f80 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
36f90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36fa0 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
36fb0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
36fc0 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
36fd0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
36fe0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
36ff0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
37000 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37010 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
37020 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
37030 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
37040 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
37050 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
37060 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
37070 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
37080 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
37090 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
370a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
370b0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
370c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
370d0 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
370e0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
370f0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
37100 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
37110 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
37120 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
37130 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
37140 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
37150 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
37160 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
37170 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37180 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
37190 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
371a0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
371b0 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
371c0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
371d0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
371e0 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
371f0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
37200 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37210 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
37220 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37230 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
37240 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
37250 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
37260 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
37270 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
37280 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
37290 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
372a0 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
372b0 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
372c0 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
372d0 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
372e0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
372f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37300 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
37310 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
37320 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
37330 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
37340 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
37350 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
37360 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
37370 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
37380 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
37390 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
373a0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
373b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
373c0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
373d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
373e0 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
373f0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
37400 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
37410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37420 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37430 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
37440 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
37450 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
37460 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
37470 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
37480 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
37490 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
374a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
374b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
374c0 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
374d0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
374e0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
374f0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
37500 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
37510 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
37520 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
37530 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
37540 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
37550 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
37560 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
37570 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37580 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
37590 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
375a0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
375b0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
375c0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
375d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
375e0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
375f0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
37600 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
37610 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
37620 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
37630 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
37640 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
37650 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
37660 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
37670 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
37680 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37690 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
376a0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
376b0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
376c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
376d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
376e0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
376f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37700 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
37710 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37720 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
37730 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
37740 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
37750 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
37760 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
37770 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
37780 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
37790 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
377a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
377b0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
377c0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
377d0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
377e0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
377f0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
37800 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
37810 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
37820 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
37830 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73  ively..** ^The s
37840 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37850 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  xt64() interface
37860 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
37870 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20   value of an.** 
37880 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37890 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
378a0 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  be a text string
378b0 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a   in an encoding.
378c0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ** specified by 
378d0 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c  the fifth (and l
378e0 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20  ast) parameter, 
378f0 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e  which must be on
37900 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f  e.** of [SQLITE_
37910 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
37920 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
37930 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
37940 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a  ITE_UTF16LE]..**
37950 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
37960 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
37970 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
37980 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
37990 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
379a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
379b0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
379c0 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
379d0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
379e0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
379f0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
37a00 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
37a10 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
37a20 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
37a30 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
37a40 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
37a50 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
37a60 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
37a70 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
37a80 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
37a90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37aa0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
37ab0 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
37ac0 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
37ad0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
37ae0 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
37af0 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
37b00 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
37b10 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
37b20 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
37b30 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
37b40 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20  unction result. 
37b50 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
37b60 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67  meter is non-neg
37b70 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a  ative, then it.*
37b80 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  * must be the by
37b90 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74  te offset into t
37ba0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
37bb0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
37bc0 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65  or would.** appe
37bd0 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ar if the string
37be0 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69   where NUL termi
37bf0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
37c00 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
37c10 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74  cur.** in the st
37c20 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f  ring at a byte o
37c30 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65  ffset that is le
37c40 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75  ss than the valu
37c50 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20  e of the 3rd.** 
37c60 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
37c70 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
37c80 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69  ring will contai
37c90 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  n embedded NULs 
37ca0 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  and the.** resul
37cb0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
37cc0 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74   operating on st
37cd0 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64  rings with embed
37ce0 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
37cf0 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  fined..** ^If th
37d00 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
37d10 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
37d20 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
37d30 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
37d40 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
37d50 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
37d60 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
37d70 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
37d80 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
37d90 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
37da0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
37db0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
37dc0 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
37dd0 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
37de0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
37df0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
37e00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37e10 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
37e20 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
37e30 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
37e40 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
37e50 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
37e60 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
37e70 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
37e80 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
37e90 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
37ea0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
37eb0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
37ec0 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
37ed0 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
37ee0 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
37ef0 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
37f00 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
37f10 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
37f20 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
37f30 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
37f40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37f50 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37f60 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
37f70 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
37f80 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
37f90 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
37fa0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
37fb0 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
37fc0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
37fd0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
37fe0 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
37ff0 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
38000 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
38010 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
38020 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
38030 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38040 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
38050 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
38060 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
38070 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
38080 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
38090 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
380a0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
380b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
380c0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
380d0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
380e0 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
380f0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
38100 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
38110 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
38120 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
38130 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
38140 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
38150 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
38160 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
38170 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
38180 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
38190 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
381a0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
381b0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
381c0 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
381d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
381e0 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
381f0 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
38200 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
38210 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
38220 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
38230 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
38240 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
38250 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
38260 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
38270 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
38280 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
38290 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
382a0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
382b0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
382c0 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
382d0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
382e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
382f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
38300 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
38310 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
38320 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
38330 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
38340 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
38350 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
38360 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
38370 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
38380 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
38390 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
383a0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
383b0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
383c0 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
383d0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65  DCALL sqlite3_re
383e0 73 75 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69  sult_blob64(sqli
383f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e  te3_context*,con
38400 73 74 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20  st void*,.      
38410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38420 20 20 20 20 20 73 71 6c 69 74 65 33 5f 75 69 6e       sqlite3_uin
38430 74 36 34 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  t64,void(*)(void
38440 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
38450 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
38460 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ALL sqlite3_resu
38470 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
38480 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
38490 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
384a0 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
384b0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ALL sqlite3_resu
384c0 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
384d0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
384e0 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51   char*, int);.SQ
384f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
38500 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
38510 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
38520 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
38530 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
38540 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
38550 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  API void SQLITE_
38560 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
38570 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
38580 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
38590 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
385a0 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
385b0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65  DCALL sqlite3_re
385c0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
385d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
385e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
385f0 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
38600 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  LL sqlite3_resul
38610 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
38620 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
38630 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
38640 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
38650 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ALL sqlite3_resu
38660 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
38670 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53  ontext*, int);.S
38680 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
38690 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
386a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
386b0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
386c0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
386d0 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
386e0 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
386f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ALL sqlite3_resu
38700 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
38710 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
38720 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
38730 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
38740 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
38750 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
38760 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
38770 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
38780 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20