/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 278df052181b0e5b0bcdb2089ff09596ae9eca15:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
39c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
39d0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
39e0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
39f0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3a00: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3a10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3a30: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3a40: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3a50: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3a60: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3a70: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3a80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
3a90: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
3aa0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
3ab0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
3ac0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
3ad0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
3ae0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3af0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3b00: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3b10: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3b20: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3b30: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3b40: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3b50: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3b60: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3b70: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3b80: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b90: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ba0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3bb0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3bc0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3bd0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3be0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3c00: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3c10: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c20: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3c30: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3c40: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3c50: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3c60: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3c70: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3c80: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3c90: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3ca0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3cb0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3cc0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3cd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3ce0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3cf0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3d00: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3d10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3d20: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3d30: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3d40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3d50: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3d60: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3d70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3d80: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3d90: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3da0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3db0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3dc0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3dd0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3de0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3df0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3e00: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3e10: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3e20: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3e30: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3e40: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3e50: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3e60: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3e70: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3e80: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3e90: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3ea0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3eb0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3ec0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3ed0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3ee0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3ef0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
3f00: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f10: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f20: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3f30: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f50: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3f70: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
3f80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3f90: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
3fa0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
3fb0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3fc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3fd0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3fe0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3ff0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
4000: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
4010: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
4020: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
4030: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
4040: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
4050: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
4060: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4070: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4080: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
4090: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
40a0: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40d0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
40e0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
40f0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
4120: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4130: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4140: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4150: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4160: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4170: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
41b0: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
41c0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
41f0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
4200: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
4210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
4220: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4250: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4260: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4270: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4290: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
42a0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
42b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
42c0: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
42d0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
42e0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
42f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
4300: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4310: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
4320: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4330: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4340: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4350: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4360: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4370: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4380: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4390: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
43a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
43b0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
43c0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
43d0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
43e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43f0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4400: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
4410: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
4420: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4430: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4440: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4450: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4460: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4470: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4480: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4490: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
44a0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44c0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
44e0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
44f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4500: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4510: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4520: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4530: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4540: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4550: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4560: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4590: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
45a0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
45b0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
45c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
45d0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
45e0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
45f0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4600: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4620: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4630: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4640: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4650: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4660: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4670: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4680: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4690: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
46a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
46b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
46c0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
46d0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
46e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4710: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4720: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4730: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4760: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4770: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4780: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4790: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
47a0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
47b0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
47c0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
47d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
47e0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
47f0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4800: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4810: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4820: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4830: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4840: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4850: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4860: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4870: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4880: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
48a0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
48b0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
48c0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
48d0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
48e0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
48f0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4900: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4920: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4930: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4940: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4960: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4970: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4980: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4990: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
49b0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
49c0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
49d0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
49e0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
49f0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4a00: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4a10: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4a30: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4a40: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4a50: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4a60: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a80: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a90: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4aa0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4ab0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ad0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4ae0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4af0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b10: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4b20: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4b30: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4b40: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4c40: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4c50: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4c60: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4c70: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4c80: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4c90: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4ca0: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4cb0: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4cc0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4cd0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4ce0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4cf0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4d00: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4d10: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4d20: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4d30: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4d40: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4d50: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4d60: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4d70: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4d80: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4d90: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4da0: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
4db0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
4dc0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
4dd0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
4de0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
4df0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
4e00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
4e10: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4e20: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
4e30: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
4e40: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
4e50: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
4e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4e70: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
4e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
4e90: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
4ea0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
4eb0: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
4ec0: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
4ed0: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
4ee0: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
4ef0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
4f00: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
4f10: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
4f20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4f30: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4f40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4f50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4f60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4f70: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4f80: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4fa0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4fb0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4fc0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fd0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ff0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
5000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5010: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5020: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
5030: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
5040: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
5050: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5060: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
5070: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
5080: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
5090: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
50a0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
50b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
50c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
50d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50e0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
50f0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
5110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5120: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
5130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5140: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
5150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5160: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
5170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5180: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
51b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51c0: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
51d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51e0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
51f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5200: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
5210: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5220: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
5230: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5240: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
5250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5260: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
5270: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
5280: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
5290: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52a0: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
52b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52c0: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
52d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52e0: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
52f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5300: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
5310: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5320: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
5330: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5340: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5350: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5360: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5370: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5380: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5390: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53a0: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
53b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53c0: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
53d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53e0: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
53f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5400: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
5410: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5420: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
5430: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5440: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5450: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5460: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5470: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5480: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5490: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54a0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
54b0: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
54c0: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
54d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54e0: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
54f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5500: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
5510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5520: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
5530: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5540: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
5550: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5560: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
5570: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5580: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
5590: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55a0: 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20  _IOERR_VNODE    
55b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
55c0: 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29  _IOERR | (27<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55e0: 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20  _IOERR_AUTH     
55f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5600: 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29  _IOERR | (28<<8)
5610: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5620: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
5630: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5640: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5650: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5660: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
5670: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5680: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
5690: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56a0: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
56b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56c0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
56f0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
5700: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5710: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5720: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
5730: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
5740: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5750: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5760: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5770: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
5780: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5790: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
57b0: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
57c0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
57d0: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
57e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
57f0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5800: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5810: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5830: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5850: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
5860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5870: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
5880: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5890: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
58a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58b0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
58c0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
58d0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
58e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58f0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
5900: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
5910: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
5920: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5930: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5940: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5950: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5960: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5970: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5980: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
59a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
59b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59c0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
59d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59e0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
59f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a00: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5a10: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5a20: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5a50: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5a60: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5a70: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5a90: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5aa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ab0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5ac0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ad0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5ae0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5af0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5b10: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5b20: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5b30: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b50: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5b60: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5b70: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5b80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5ba0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5bb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5bc0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5bd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5be0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5bf0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c00: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c20: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c60: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c70: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c80: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5ca0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5cb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5cc0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
5cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
5ce0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
5cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
5d00: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
5d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5d20: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5d30: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5d40: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5d50: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5d60: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5d70: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5d80: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d90: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5da0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5db0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5dc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5de0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5e00: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5e10: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5e20: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e30: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5e50: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5e60: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5e70: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e80: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5ea0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5eb0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5ec0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ed0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5ef0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5f00: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5f10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5f30: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5f40: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5f50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5f70: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5f80: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5f90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5fa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5fb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5fc0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5fd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fe0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
6000: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6010: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
6020: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6030: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6060: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6090: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
60a0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
60d0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
60e0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6120: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6150: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6160: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6170: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6190: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
61a0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
61b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
61d0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
61e0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
61f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6210: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6220: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6230: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6240: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6260: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6270: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6280: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6290: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
62b0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
62c0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
62d0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62e0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6300: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6310: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6320: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6330: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6340: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6350: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6360: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6370: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6380: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6390: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
63a0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
63b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
63c0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
63d0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
63e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
63f0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6400: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6410: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6420: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6430: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6440: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6450: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6460: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6470: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6480: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6490: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
64a0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
64b0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
64c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
64d0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
64e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
64f0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6500: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6510: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6520: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6530: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6540: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6550: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6560: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6570: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6580: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6590: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
65a0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
65b0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
65c0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
65d0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
65e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
65f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6600: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6610: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6620: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6630: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6640: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6650: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6660: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6670: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6680: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6690: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
66a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
66b0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
66c0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
66d0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
66e0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
66f0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6700: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6710: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6720: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6730: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6740: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6750: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6760: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6770: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6780: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6790: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
67a0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
67b0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
67c0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
67d0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
67e0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
67f0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6800: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6810: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6820: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6830: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6840: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6850: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6860: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6870: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
6880: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6890: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
68a0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
68b0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
68c0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
68d0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
68e0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
68f0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6900: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6910: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6920: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6930: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6950: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6960: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6970: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6980: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6990: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
69a0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
69b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69c0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
69d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
69e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a10: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a30: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6a40: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a60: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6a70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a80: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6aa0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6ab0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ad0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6ae0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6af0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6b10: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6b20: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6b60: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6b80: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6b90: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6bb0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6bc0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6be0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6bf0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6c00: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6c20: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6c30: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6c40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6c50: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6c60: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6c70: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6c80: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6c90: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6ca0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6cb0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6cc0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6cd0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6ce0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6cf0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6d00: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6d10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6d20: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6d30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6d40: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6d50: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6d60: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6d70: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6d80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6d90: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6da0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6db0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6dc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6dd0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6de0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6df0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6e00: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6e10: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6e20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6e30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6e40: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6e50: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6e60: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6e70: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6e80: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6e90: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6ea0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6eb0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6ec0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6ed0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6ee0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6ef0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6f00: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
6f10: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
6f20: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
6f30: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6f40: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
6f50: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
6f60: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
6f70: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
6f80: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6f90: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
6fa0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6fb0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
6fc0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
6fd0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
6fe0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
6ff0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7000: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7010: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7020: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7030: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7040: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7050: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7060: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
7070: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
7080: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
7090: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
70a0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
70b0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
70c0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
70d0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
70e0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
70f0: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7100: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7110: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7120: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7130: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7140: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7150: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7160: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
7170: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
7180: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
7190: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
71a0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
71b0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
71c0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
71d0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
71e0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
71f0: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7200: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7210: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7220: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7230: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7240: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7250: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7260: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
7270: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
7280: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
7290: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
72a0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
72b0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
72c0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
72d0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
72e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
72f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7310: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7320: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7330: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7340: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7350: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7360: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7370: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
7380: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
7390: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
73a0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
73b0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
73c0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
73d0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
73e0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
73f0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7400: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7410: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7420: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7430: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7440: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7450: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7460: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7470: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7480: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7490: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
74a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
74b0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
74c0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
74d0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
74e0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
74f0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7500: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7510: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7520: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7530: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7540: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7550: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7560: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7570: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7580: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7590: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
75a0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
75b0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
75c0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
75d0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
75e0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
75f0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7600: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7610: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7620: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7630: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7640: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7650: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7660: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7670: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7680: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7690: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
76a0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
76b0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
76c0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
76d0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
76e0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
76f0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7700: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7710: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7720: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7730: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7740: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7750: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7760: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7770: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7780: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7790: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
77a0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
77b0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
77c0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
77d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
77e0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
77f0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7800: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7810: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7820: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7830: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7840: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7850: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7860: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7870: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7880: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7890: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
78a0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
78b0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
78c0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
78d0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
78e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
78f0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7900: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7910: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7920: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7930: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7940: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7950: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7960: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7970: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7980: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7990: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
79a0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
79b0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
79c0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
79d0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
79e0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
79f0: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7a00: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7a10: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7a20: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7a30: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7a40: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7a50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a60: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7a70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7a80: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7a90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7aa0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7ab0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7ac0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7ad0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7ae0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7af0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7b00: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7b10: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7b20: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7b30: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7b40: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7b50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7b60: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7b70: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7b80: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7b90: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7ba0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7bb0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7bc0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7bd0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7be0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7bf0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7c00: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7c10: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7c20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7c30: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7c40: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7c50: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7c60: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7c70: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7c80: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7c90: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7ca0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7cb0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7cc0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7cd0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7ce0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7cf0: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7d00: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7d10: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7d20: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7d30: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7d40: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7d50: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7d60: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7d70: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7d80: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7d90: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7da0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7db0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7dc0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7dd0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7de0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7df0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7e00: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7e10: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7e20: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7e30: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7e40: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7e50: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7e60: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7e70: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7e80: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7e90: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7ea0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7eb0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7ec0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7ed0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7ee0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7ef0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7f00: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7f10: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7f20: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7f30: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7f40: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7f50: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7f60: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7f70: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7f80: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7f90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7fa0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7fb0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
7fc0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7fd0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
7fe0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
7ff0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8000: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8010: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8020: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8030: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8040: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8050: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8060: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
8070: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
8080: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8090: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
80a0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
80b0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
80c0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
80d0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
80e0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
80f0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8100: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8110: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8120: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8130: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8140: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8150: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8160: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8170: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
8180: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8190: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81b0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
81c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81d0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
81e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81f0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8200: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8210: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8220: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8230: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8240: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8250: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8260: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8270: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
8280: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8290: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
82a0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
82b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
82c0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
82d0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
82e0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
82f0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8300: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8310: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8320: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8330: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8340: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8350: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8360: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8370: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8380: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8390: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
83a0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
83b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
83c0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
83d0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
83e0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
83f0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8400: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8410: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8420: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8430: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8440: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8450: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8460: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8470: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8480: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8490: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
84a0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
84b0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
84c0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
84d0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
84e0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
84f0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8500: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8510: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8520: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8530: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8540: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8550: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8560: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8570: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8580: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8590: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
85a0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
85b0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
85c0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
85d0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
85e0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
85f0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8600: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8610: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8620: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8630: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8640: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8650: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8660: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8670: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8680: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8690: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86a0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
86b0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
86c0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
86d0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
86e0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
86f0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8700: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8710: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8720: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8730: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8740: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8750: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8760: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8770: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8780: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8790: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
87a0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
87b0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
87c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
87d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
87e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
87f0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8800: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8810: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8820: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8830: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8840: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8850: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8860: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8870: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8880: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8890: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
88a0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
88c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
88d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
88e0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
88f0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8900: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8910: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8920: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8930: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8940: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8950: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8960: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8970: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8980: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8990: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
89a0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
89b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89c0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
89d0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
89e0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
89f0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8a00: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8a10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a20: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8a30: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8a40: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8a50: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8a60: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8a70: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8a80: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8a90: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8aa0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ab0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8ac0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8ad0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8ae0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8af0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8b00: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8b10: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8b20: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8b30: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8b40: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8b50: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8b60: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8b70: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8b80: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8b90: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8ba0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8bb0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8bc0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8bd0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8be0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8bf0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8c00: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8c10: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8c20: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8c30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c40: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8c50: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8c60: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8c70: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8c80: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8c90: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8ca0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8cb0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8cc0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8cd0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ce0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8cf0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8d00: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8d10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8d20: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8d30: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8d40: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8d50: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8d60: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8d70: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8d80: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8d90: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8da0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8db0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8dc0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8dd0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8de0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8df0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8e00: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8e10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8e20: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8e30: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8e40: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8e50: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8e60: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8e70: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8e80: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8e90: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8ea0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8eb0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8ec0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8ed0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8ee0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8ef0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8f00: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8f10: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8f20: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8f30: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8f40: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8f50: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8f60: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8f70: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8f80: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8f90: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8fa0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8fb0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8fc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8fd0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8fe0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8ff0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
9000: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9010: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9020: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9030: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9040: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9050: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9060: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9070: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9080: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9090: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
90a0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
90b0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
90c0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
90d0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
90e0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
90f0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
9100: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9110: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9120: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9130: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9140: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9150: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9160: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9170: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9180: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9190: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
91a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
91b0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
91c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
91d0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
91e0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
91f0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9200: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9210: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9220: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9230: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9240: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9250: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
9260: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9270: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
9280: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9290: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
92a0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
92b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
92c0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
92d0: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
92e0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
92f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9300: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9310: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9320: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9330: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9340: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9350: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9360: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
9370: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
9380: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9390: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
93a0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
93b0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
93c0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
93d0: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
93e0: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
93f0: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9400: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9410: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9420: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9430: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9440: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9450: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9460: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
9470: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
9480: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9490: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
94a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
94b0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
94c0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
94d0: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
94e0: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
94f0: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9500: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9510: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9520: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
9530: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
9540: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
9550: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9560: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
9570: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
9580: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9590: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
95a0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
95b0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
95c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
95d0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
95e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
95f0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9600: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9610: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9620: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
9630: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9640: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9650: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9660: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9670: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9680: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9690: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
96a0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
96b0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
96c0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
96d0: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
96e0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
96f0: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9700: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9710: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9720: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
9730: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
9740: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
9750: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9760: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9770: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
9780: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9790: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
97a0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
97b0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
97c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
97d0: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
97e0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
97f0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9800: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9810: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9820: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9830: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9840: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9850: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9860: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9880: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9890: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
98a0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
98b0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
98c0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
98d0: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
98e0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
98f0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9900: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9910: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9920: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9930: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9940: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9950: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9960: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9970: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9980: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9990: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
99a0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
99b0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
99c0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
99d0: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
99e0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
99f0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9a00: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9a10: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9a20: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9a30: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9a40: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9a50: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9a60: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9a70: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9a80: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9a90: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9aa0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9ab0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9ac0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9ad0: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9ae0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9af0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9b00: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9b10: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9b20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9b30: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9b40: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9b50: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9b60: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9b70: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9b80: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9b90: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9ba0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9bb0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9bc0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9bd0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9be0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9bf0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9c00: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9c10: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9c20: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9c30: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9c40: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9c50: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9c60: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9c70: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9c80: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9c90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9ca0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9cb0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9cc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9cd0: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9ce0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9cf0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9d00: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9d10: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9d20: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9d30: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9d40: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9d50: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9d60: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9d70: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9d80: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9d90: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9da0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9db0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9dc0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9dd0: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9de0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9df0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9e00: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9e10: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9e20: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9e30: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9e40: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9e50: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9e60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9e70: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9e80: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9e90: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9ea0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9eb0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9ec0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9ed0: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9ee0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9ef0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9f00: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9f10: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9f20: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9f30: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9f40: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9f50: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9f60: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9f70: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9f80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9f90: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9fa0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9fb0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9fc0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9fd0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9fe0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9ff0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a000: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a010: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a020: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a030: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a040: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a050: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a060: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a070: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a080: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a090: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a0a0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a0b0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a0c0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a0d0: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a0e0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a0f0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a100: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a110: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a120: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a140: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a150: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a160: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a170: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a180: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a190: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a1a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a1b0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a1c0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a1d0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a1e0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a1f0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a200: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a210: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a220: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a230: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a240: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a250: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a260: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a270: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a280: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a290: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a2a0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a2b0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a2d0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a2e0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a2f0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a300: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a310: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a320: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a330: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a340: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a350: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a360: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a370: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a380: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a390: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a3a0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a3b0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a3c0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a3d0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a3e0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a3f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a400: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a410: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a420: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a430: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a440: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a450: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a460: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a470: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a480: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a490: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a4a0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a4b0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a4c0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a4d0: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a4e0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a4f0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a500: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a510: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a520: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a530: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a540: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a550: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a560: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a570: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a580: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a590: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a5a0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a5b0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a5c0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a5d0: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a5e0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a5f0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a600: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a610: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a620: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a630: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a640: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a650: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a660: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a670: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a680: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a690: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a6a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a6b0: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a6c0: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a6d0: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a6e0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a6f0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a700: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a710: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a720: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a730: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a740: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a750: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a760: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a770: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a780: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a790: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a7a0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a7b0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a7c0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a7d0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a7e0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a7f0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a800: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a810: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a820: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a830: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a840: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a850: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a860: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a870: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a880: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a890: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a8a0: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a8b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a8c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a8d0: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a8e0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a8f0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a900: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a910: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a920: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a930: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a940: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a950: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a960: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a970: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a980: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a990: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a9a0: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a9b0: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a9c0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a9d0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a9e0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a9f0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
aa00: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
aa10: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
aa20: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
aa30: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
aa40: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
aa50: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
aa60: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
aa70: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
aa80: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
aa90: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
aaa0: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
aab0: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
aac0: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
aad0: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
aae0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
aaf0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
ab00: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
ab10: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
ab20: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
ab30: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
ab40: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
ab50: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
ab60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab70: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ab80: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
ab90: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
aba0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
abb0: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
abc0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
abd0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
abe0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
abf0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
ac00: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
ac10: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
ac20: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
ac30: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
ac40: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
ac50: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
ac60: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
ac70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
ac80: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
ac90: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
aca0: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
acb0: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
acc0: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
acd0: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
ace0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
acf0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ad00: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
ad10: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
ad20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
ad30: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
ad40: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
ad50: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
ad60: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
ad70: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
ad80: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ad90: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ada0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
adb0: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
adc0: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
add0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ade0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
adf0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ae00: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
ae10: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ae20: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
ae30: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
ae40: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
ae50: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
ae60: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
ae70: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
ae80: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
ae90: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
aea0: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
aeb0: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
aec0: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
aed0: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
aee0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
aef0: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
af00: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
af10: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
af20: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
af30: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
af40: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
af50: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
af60: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
af70: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
af80: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
af90: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
afa0: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
afb0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
afc0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
afd0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
afe0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
aff0: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
b000: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b010: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
b020: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
b030: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
b040: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b050: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b060: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b070: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b080: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b090: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b0a0: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b0b0: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b0c0: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b0d0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b0e0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b0f0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b100: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b110: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b120: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b130: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b140: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b150: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b160: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b170: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b180: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b190: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b1a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b1b0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b1c0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b1d0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b1e0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b1f0: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b200: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b210: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b220: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b230: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b240: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b250: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b260: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b270: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b280: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b290: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b2a0: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b2b0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b2c0: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b2d0: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b2e0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b2f0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b300: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b310: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b320: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b330: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b340: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b350: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b360: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b370: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b380: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b390: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b3a0: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b3b0: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b3c0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b3d0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b3e0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b3f0: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b400: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b410: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b420: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b430: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b440: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b450: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b460: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b470: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b480: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b490: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b4a0: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b4b0: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b4c0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b4d0: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b4e0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b4f0: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b500: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b510: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b520: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b530: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
b540: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
b550: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
b560: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
b570: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
b580: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
b590: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
b5a0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
b5b0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
b5c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b5d0: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
b5e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
b5f0: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
b600: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
b610: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
b620: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
b630: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
b640: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
b650: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
b660: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
b670: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
b680: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
b690: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
b6a0: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
b6b0: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
b6c0: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
b6d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b6e0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b6f0: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
b700: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b710: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b720: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
b730: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
b740: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
b750: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
b760: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
b770: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
b780: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
b790: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
b7a0: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
b7b0: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
b7c0: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
b7d0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b7e0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
b7f0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
b800: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
b810: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
b820: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b830: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
b840: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
b850: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
b860: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
b870: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
b880: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
b890: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
b8a0: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
b8b0: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
b8c0: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
b8d0: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
b8e0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
b8f0: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
b900: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
b910: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
b920: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
b930: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
b940: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
b950: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
b960: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
b970: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
b980: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
b990: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
b9a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b9b0: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
b9c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b9d0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
b9e0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
b9f0: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
ba00: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
ba10: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
ba20: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
ba30: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
ba40: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
ba50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
ba60: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
ba70: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
ba80: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
ba90: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
baa0: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
bab0: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
bac0: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
bad0: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
bae0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
baf0: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
bb00: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20  is opcode.  .** 
bb10: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
bb20: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
bb30: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
bb40: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
bb50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
bb60: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
bb70: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
bb80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
bb90: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bba0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
bbb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
bbc0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
bbd0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
bbe0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
bbf0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
bc00: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
bc10: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
bc20: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
bc30: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
bc40: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
bc50: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
bc60: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
bc70: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
bc80: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
bc90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bca0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
bcb0: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
bcc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bcd0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
bce0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
bcf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bd00: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
bd10: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
bd20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bd30: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
bd40: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
bd50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bd60: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
bd70: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
bd80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bd90: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
bda0: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
bdb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bdc0: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
bdd0: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
bde0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
bdf0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
be00: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
be10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
be20: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
be30: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
be40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
be50: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
be60: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
be70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
be80: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
be90: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
bea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
beb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bec0: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
bed0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
bee0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
bef0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
bf00: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
bf10: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
bf20: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
bf30: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
bf40: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
bf50: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
bf60: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
bf70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
bf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf90: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
bfa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
bfb0: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
bfc0: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
bfd0: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
bfe0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
bff0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
c000: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
c010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
c020: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c030: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c040: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c050: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c060: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c070: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
c080: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
c090: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c0a0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
c0b0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
c0c0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
c0d0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
c0e0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
c0f0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
c100: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
c110: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
c120: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c130: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c140: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c150: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c160: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c170: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c180: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c190: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c1a0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c1b0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c1c0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c1d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c1e0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c1f0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c200: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c210: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c220: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
c230: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
c240: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
c250: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c260: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
c270: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
c280: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
c290: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
c2a0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
c2b0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
c2c0: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
c2d0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
c2e0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
c2f0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
c300: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
c310: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
c320: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
c330: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
c340: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
c350: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
c360: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
c370: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
c380: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
c390: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
c3a0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
c3b0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
c3c0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
c3d0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
c3e0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
c3f0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
c400: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
c410: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
c420: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
c430: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
c440: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
c450: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
c460: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
c470: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
c480: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
c490: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
c4a0: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
c4b0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
c4c0: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
c4d0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c4e0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
c4f0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
c500: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
c510: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
c520: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
c530: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
c540: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
c550: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
c560: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
c570: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
c580: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
c590: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
c5a0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
c5b0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
c5c0: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
c5d0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
c5e0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
c5f0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
c600: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
c610: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
c620: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
c630: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c640: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
c650: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
c660: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
c670: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c680: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
c690: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
c6a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
c6b0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c6c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
c6d0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
c6e0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
c6f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c700: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
c710: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
c720: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
c730: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
c740: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
c750: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
c760: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
c770: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
c780: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
c790: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
c7a0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
c7b0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
c7c0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
c7d0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
c7e0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
c7f0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
c800: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
c810: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
c820: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
c830: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
c840: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
c850: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
c860: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
c870: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
c880: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
c890: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
c8a0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c8b0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
c8c0: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
c8d0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
c8e0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
c8f0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
c900: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
c910: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
c920: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
c930: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
c940: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c950: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
c960: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
c970: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
c980: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
c990: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
c9a0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
c9b0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
c9c0: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
c9d0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
c9e0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
c9f0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
ca00: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
ca10: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
ca20: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
ca30: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
ca40: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
ca50: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
ca60: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
ca70: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
ca80: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
ca90: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
caa0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
cab0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
cac0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
cad0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
cae0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
caf0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
cb00: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
cb10: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
cb20: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
cb30: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
cb40: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
cb50: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
cb60: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
cb70: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
cb80: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
cb90: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
cba0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
cbb0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
cbc0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cbd0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
cbe0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
cbf0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
cc00: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
cc10: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
cc20: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
cc30: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
cc40: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
cc50: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
cc60: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
cc70: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
cc80: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
cc90: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
cca0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
ccb0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
ccc0: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
ccd0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
cce0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
ccf0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
cd00: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
cd10: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
cd20: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
cd30: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
cd40: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
cd50: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
cd60: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
cd70: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
cd80: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
cd90: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
cda0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
cdb0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
cdc0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
cdd0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
cde0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
cdf0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ce00: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
ce10: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
ce20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
ce30: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
ce40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
ce50: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ce60: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
ce70: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
ce80: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ce90: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
cea0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ceb0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
cec0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ced0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
cee0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
cef0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
cf00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
cf10: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
cf20: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
cf30: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
cf40: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
cf50: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
cf60: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
cf70: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
cf80: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
cf90: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
cfa0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
cfb0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
cfc0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
cfd0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
cfe0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
cff0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
d000: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
d010: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
d020: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
d030: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
d040: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
d050: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
d060: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
d070: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
d080: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
d090: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
d0a0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
d0b0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
d0c0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
d0d0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
d0e0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
d0f0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
d100: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
d110: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
d120: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
d130: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
d140: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
d150: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
d160: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d170: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
d180: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
d190: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
d1a0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
d1b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d1c0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
d1d0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
d1e0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
d1f0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
d200: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
d210: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d220: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
d230: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
d240: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
d250: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
d260: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
d270: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
d280: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
d290: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
d2a0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
d2b0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
d2c0: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
d2d0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
d2e0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
d2f0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
d300: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
d310: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
d320: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
d330: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
d340: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
d350: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
d360: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
d370: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
d380: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
d390: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d3a0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
d3b0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
d3c0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
d3d0: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
d3e0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
d3f0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
d400: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
d410: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
d420: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
d430: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
d440: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
d450: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
d460: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
d470: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
d480: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
d490: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
d4a0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
d4b0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
d4c0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
d4d0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
d4e0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
d4f0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
d500: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
d510: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
d520: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
d530: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
d540: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
d550: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
d560: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d570: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
d580: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d590: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
d5a0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
d5b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
d5c0: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
d5d0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
d5e0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
d5f0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
d600: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
d610: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
d620: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
d630: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
d640: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
d650: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
d660: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
d670: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
d680: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
d690: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
d6a0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
d6b0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
d6c0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
d6d0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
d6e0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d6f0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
d700: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
d710: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
d720: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d730: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
d740: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d750: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
d760: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
d770: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d780: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
d790: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
d7a0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
d7b0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
d7c0: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
d7d0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
d7e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
d7f0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
d800: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
d810: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
d820: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
d830: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
d840: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
d850: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
d860: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
d870: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
d880: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
d890: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
d8a0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d8b0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
d8c0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
d8d0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
d8e0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
d8f0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
d900: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
d910: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
d920: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
d930: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
d940: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
d950: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
d960: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
d970: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
d980: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
d990: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d9a0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
d9b0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
d9c0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
d9d0: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
d9e0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
d9f0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
da00: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
da10: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
da20: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
da30: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
da40: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
da50: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
da60: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
da70: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
da80: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
da90: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
daa0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
dab0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
dac0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
dad0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
dae0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
daf0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
db00: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
db10: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
db20: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
db30: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
db40: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
db50: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
db60: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
db70: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
db80: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
db90: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
dba0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
dbb0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
dbc0: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
dbd0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
dbe0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
dbf0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dc00: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
dc10: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
dc20: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
dc30: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
dc40: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
dc50: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
dc60: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
dc70: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
dc80: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
dc90: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
dca0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dcb0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
dcc0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
dcd0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
dce0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
dcf0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
dd00: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
dd10: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
dd20: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
dd30: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
dd40: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
dd50: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
dd60: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
dd70: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
dd80: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
dd90: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
dda0: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
ddb0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
ddc0: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
ddd0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
dde0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
ddf0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
de00: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
de10: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
de20: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
de30: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
de40: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
de50: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
de60: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
de70: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
de80: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
de90: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
dea0: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
deb0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
dec0: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
ded0: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
dee0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
def0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
df00: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
df10: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
df20: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
df30: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
df40: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
df50: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
df60: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
df70: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
df80: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
df90: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
dfa0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
dfb0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
dfc0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
dfd0: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
dfe0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
dff0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
e000: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
e010: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
e020: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
e030: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
e040: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
e050: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
e060: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
e070: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
e080: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
e090: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
e0a0: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
e0b0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
e0c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
e0d0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
e0e0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
e0f0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
e100: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
e110: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
e120: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
e130: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
e140: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
e150: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
e160: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
e170: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
e180: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
e190: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
e1a0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
e1b0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
e1c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
e1d0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
e1e0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
e1f0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
e200: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
e210: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
e220: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
e230: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
e240: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
e250: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
e260: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
e270: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
e280: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
e290: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
e2a0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
e2b0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
e2c0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e2d0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e2e0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
e2f0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
e300: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
e310: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
e320: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
e330: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e340: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
e350: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
e360: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
e370: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e380: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
e390: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
e3a0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
e3b0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
e3c0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e3d0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
e3e0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
e3f0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
e400: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e410: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
e420: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
e430: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
e440: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e450: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
e460: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
e470: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
e480: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
e490: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
e4a0: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
e4b0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
e4c0: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
e4d0: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
e4e0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
e4f0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
e500: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
e510: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
e520: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
e530: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
e540: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e550: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e560: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
e570: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
e580: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e590: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
e5a0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e5b0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e5c0: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
e5d0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e5e0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
e5f0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
e600: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
e610: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
e620: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
e630: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e640: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
e650: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
e660: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
e670: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e680: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e690: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
e6a0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e6b0: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
e6c0: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
e6d0: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
e6e0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
e6f0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
e700: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e710: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e720: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
e730: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
e740: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
e750: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
e760: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e770: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e780: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
e790: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
e7a0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
e7b0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e7c0: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
e7d0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e7e0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e7f0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
e800: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e810: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
e820: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
e830: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
e840: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
e850: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
e860: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
e870: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
e880: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
e890: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
e8a0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
e8b0: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
e8c0: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
e8d0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
e8e0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
e8f0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
e900: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
e910: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e920: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
e930: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
e940: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
e950: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
e960: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
e970: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
e980: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
e990: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e9a0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
e9b0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
e9c0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
e9d0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
e9e0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
e9f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ea00: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
ea10: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
ea20: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
ea30: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
ea40: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
ea50: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
ea60: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
ea70: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
ea80: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
ea90: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
eaa0: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
eab0: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
eac0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ead0: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
eae0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
eaf0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
eb00: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
eb10: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
eb20: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
eb30: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
eb40: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
eb50: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
eb60: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
eb70: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
eb80: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
eb90: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
eba0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
ebb0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
ebc0: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
ebd0: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
ebe0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
ebf0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
ec00: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
ec10: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
ec20: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
ec30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ec40: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
ec50: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ec60: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
ec70: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
ec80: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
ec90: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
eca0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ecb0: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
ecc0: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
ecd0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
ece0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
ecf0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
ed00: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
ed10: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
ed20: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
ed30: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
ed40: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
ed50: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
ed60: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
ed70: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
ed80: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
ed90: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
eda0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
edb0: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
edc0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
edd0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ede0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
edf0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
ee00: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
ee10: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
ee20: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
ee30: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
ee40: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
ee50: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
ee60: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
ee70: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ee80: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ee90: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
eea0: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
eeb0: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
eec0: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
eed0: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
eee0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
eef0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
ef00: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
ef10: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
ef20: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
ef30: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
ef40: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
ef50: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
ef60: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
ef70: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
ef80: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
ef90: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
efa0: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
efb0: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
efc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
efd0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
efe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
eff0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
f000: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
f010: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
f020: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
f030: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f040: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
f050: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
f060: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
f070: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f080: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
f090: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
f0a0: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
f0b0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
f0c0: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
f0d0: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
f0e0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
f0f0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
f100: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
f110: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
f120: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
f130: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
f140: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
f150: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
f160: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
f170: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f180: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
f190: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f1a0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f1b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f1c0: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
f1d0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
f1e0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
f1f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f200: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
f210: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
f220: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
f230: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
f240: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f250: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
f260: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
f270: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
f280: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
f290: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
f2a0: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
f2b0: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
f2c0: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
f2d0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
f2e0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
f2f0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
f300: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
f310: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
f320: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
f330: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f340: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f350: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
f360: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
f370: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f380: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f390: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
f3a0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
f3b0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
f3c0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
f3d0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
f3e0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
f3f0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
f400: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
f410: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
f420: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
f430: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
f440: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f450: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
f460: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
f470: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
f480: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
f490: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
f4a0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f4b0: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
f4c0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
f4d0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f4e0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
f4f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f500: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
f510: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f520: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
f530: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
f540: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f550: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
f560: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
f570: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
f580: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
f590: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f5a0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
f5b0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
f5c0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
f5d0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
f5e0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
f5f0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
f600: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
f610: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
f620: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
f630: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
f640: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
f650: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
f660: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
f670: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f680: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
f690: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
f6a0: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
f6b0: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
f6c0: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
f6d0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
f6e0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f6f0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
f700: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
f710: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f720: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
f730: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f740: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
f750: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
f760: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
f770: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
f780: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
f790: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f7a0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
f7b0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
f7c0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
f7d0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
f7e0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
f7f0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
f800: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
f810: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
f820: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
f830: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
f840: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
f850: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
f860: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
f870: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
f880: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
f890: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
f8a0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f8b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f8c0: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
f8d0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
f8e0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
f8f0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
f900: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
f910: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
f920: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
f930: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
f940: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f950: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
f960: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
f970: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
f980: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f990: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
f9a0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
f9b0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
f9c0: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
f9d0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
f9e0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
f9f0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
fa00: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
fa10: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
fa20: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
fa30: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
fa40: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
fa50: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
fa60: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
fa70: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
fa80: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
fa90: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
faa0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
fab0: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
fac0: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
fad0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fae0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
faf0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
fb00: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
fb10: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
fb20: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
fb30: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
fb40: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
fb50: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
fb60: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
fb70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
fb80: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
fb90: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
fba0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fbb0: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
fbc0: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
fbd0: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
fbe0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
fbf0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
fc00: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
fc10: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
fc20: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
fc30: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
fc40: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
fc50: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
fc60: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
fc70: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
fc80: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
fc90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
fca0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
fcb0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
fcc0: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
fcd0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fce0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
fcf0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
fd00: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fd10: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
fd20: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
fd30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
fd40: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
fd50: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
fd60: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
fd70: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
fd80: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
fd90: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
fda0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
fdb0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
fdc0: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
fdd0: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
fde0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
fdf0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
fe00: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
fe10: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
fe20: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
fe30: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
fe40: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
fe50: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
fe60: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
fe70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fe80: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
fe90: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
fea0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
feb0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
fec0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
fed0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
fee0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
fef0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
ff00: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
ff10: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
ff20: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
ff30: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
ff40: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
ff50: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ff60: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
ff70: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ff80: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
ff90: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ffa0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
ffb0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
ffc0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
ffd0: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
ffe0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
fff0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
10000 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
10010 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
10020 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
10030 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
10040 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
10050 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
10060 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
10070 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
10080 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
10090 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
100a0 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
100b0 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
100c0 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
100d0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
100e0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
100f0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
10100 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
10110 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
10120 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
10130 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10140 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
10150 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10160 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
10170 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
10180 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
10190 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
101a0 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
101b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
101c0 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
101d0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
101e0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
101f0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
10200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10210 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
10220 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10230 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
10240 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10250 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10260 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
10270 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10280 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
10290 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
102a0 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
102b0 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
102c0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
102d0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
102e0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
102f0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
10300 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
10310 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
10320 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
10330 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
10340 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
10350 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
10360 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
10370 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
10380 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
10390 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
103a0 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
103b0 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
103c0 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
103d0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
103e0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
103f0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
10400 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
10410 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
10420 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
10430 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10440 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
10450 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
10460 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10470 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
10480 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
10490 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
104a0 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
104b0 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
104c0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
104d0 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
104e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
104f0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
10500 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
10510 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
10520 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10530 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
10540 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10550 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
10560 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
10570 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
10580 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
10590 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
105a0 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
105b0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
105c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
105d0 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
105e0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
105f0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
10600 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
10610 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
10620 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10630 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
10640 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10650 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
10660 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
10670 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
10680 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
10690 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
106a0 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
106b0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
106c0 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
106d0 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
106e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
106f0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
10700 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
10710 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
10720 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10730 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10740 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
10750 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
10760 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
10770 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
10780 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
10790 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
107a0 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
107b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
107c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
107d0 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
107e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
107f0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
10800 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
10810 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
10820 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
10830 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10840 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
10850 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
10860 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
10870 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
10880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
10890 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
108a0 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
108b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
108c0 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
108d0 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
108e0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
108f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10900 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
10910 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10920 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
10930 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10940 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
10950 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
10960 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
10970 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10980 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
10990 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
109a0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
109b0 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
109c0 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
109d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
109e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
109f0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
10a00 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
10a10 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
10a20 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
10a30 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10a40 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
10a50 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
10a60 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
10a70 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
10a80 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
10a90 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
10aa0 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
10ab0 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
10ac0 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
10ad0 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
10ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
10af0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
10b00 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
10b10 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10b20 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
10b30 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
10b40 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
10b50 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
10b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10b70 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
10b80 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
10b90 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
10ba0 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
10bb0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10bc0 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
10bd0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10be0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
10bf0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
10c00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10c10 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
10c20 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10c30 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
10c40 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
10c50 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
10c60 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
10c70 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
10c80 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10c90 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
10ca0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
10cb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
10cc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10cd0 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
10ce0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
10cf0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
10d00 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
10d10 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
10d20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10d30 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
10d40 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
10d50 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
10d60 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
10d70 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
10d80 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
10d90 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
10da0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
10db0 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
10dc0 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
10dd0 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
10de0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
10df0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
10e00 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
10e10 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
10e20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
10e30 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
10e40 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10e50 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
10e60 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
10e70 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
10e80 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
10e90 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
10ea0 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
10eb0 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
10ec0 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
10ed0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
10ee0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10ef0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
10f00 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
10f10 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
10f20 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
10f30 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
10f40 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
10f50 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
10f60 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
10f70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
10f80 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
10f90 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
10fa0 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
10fb0 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
10fc0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
10fd0 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
10fe0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
10ff0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
11000 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
11010 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
11020 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
11030 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
11040 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
11050 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
11060 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
11070 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
11080 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
11090 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
110a0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
110b0 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
110c0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
110d0 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
110e0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
110f0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
11100 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
11110 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
11120 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
11130 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
11140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
11150 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
11160 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
11170 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11180 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
11190 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
111a0 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
111b0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
111c0 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
111d0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
111e0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
111f0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
11200 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
11210 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
11220 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
11230 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
11240 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
11250 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
11260 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
11270 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11280 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
11290 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
112a0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
112b0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
112c0 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
112d0 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
112e0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
112f0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
11300 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
11310 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
11320 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
11330 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
11340 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
11350 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
11360 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
11370 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
11380 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
11390 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
113a0 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
113b0 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
113c0 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
113d0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
113e0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
113f0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
11400 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11410 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
11420 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
11430 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
11440 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
11450 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
11460 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
11470 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
11480 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
11490 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
114a0 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
114b0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
114c0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
114d0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
114e0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
114f0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
11500 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
11510 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
11520 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
11530 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11540 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
11550 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
11560 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
11570 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
11580 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
11590 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
115a0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
115b0 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
115c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
115d0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
115e0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
115f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
11600 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11610 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11620 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
11630 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
11640 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
11650 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
11660 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11670 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11680 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11690 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
116a0 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
116b0 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
116c0 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
116d0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
116e0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
116f0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11700 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
11710 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
11720 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
11730 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11740 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
11750 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
11760 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
11770 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
11780 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11790 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
117a0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
117b0 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
117c0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
117d0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
117e0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
117f0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11800 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11810 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
11820 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
11830 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
11840 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
11850 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
11860 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
11870 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
11880 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
11890 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
118a0 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
118b0 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
118c0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
118d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
118e0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
118f0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
11900 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
11910 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
11920 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
11930 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
11940 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
11950 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
11960 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11970 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
11980 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
11990 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
119a0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
119b0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
119c0 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
119d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
119e0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
119f0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
11a00 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
11a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11a20 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
11a30 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
11a40 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
11a50 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
11a60 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
11a70 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
11a80 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
11a90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
11aa0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
11ab0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
11ac0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
11ad0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11ae0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11af0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
11b00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11b10 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
11b20 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
11b30 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
11b40 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
11b50 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
11b60 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
11b70 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
11b80 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
11b90 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
11ba0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
11bb0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
11bc0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
11bd0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
11be0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
11bf0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11c00 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
11c10 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
11c20 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
11c30 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
11c40 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
11c50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
11c60 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
11c70 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
11c80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11c90 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
11ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11cb0 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
11cc0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11cd0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11ce0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11cf0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11d00 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11d10 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
11d20 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
11d30 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11d40 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
11d50 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
11d60 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
11d70 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
11d80 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
11d90 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
11da0 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
11db0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11dc0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11dd0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11de0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11df0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11e00 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11e10 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11e20 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
11e30 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11e40 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
11e50 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
11e60 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
11e70 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
11e80 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11e90 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
11ea0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11eb0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11ec0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11ed0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
11ee0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11ef0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11f00 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11f10 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11f20 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11f30 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11f40 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11f50 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11f60 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11f70 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11f80 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11f90 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
11fa0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
11fb0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
11fc0 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
11fd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11fe0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11ff0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
12000 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
12010 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
12020 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
12030 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
12040 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12050 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12060 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12070 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
12080 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
12090 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
120a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
120b0 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
120c0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
120d0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
120e0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
120f0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
12100 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
12110 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
12120 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
12130 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
12140 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12150 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12160 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12170 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12180 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12190 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
121a0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
121b0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
121c0 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
121d0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
121e0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
121f0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12200 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12210 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
12220 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
12230 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12240 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
12250 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12260 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12270 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12280 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12290 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
122a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
122b0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
122c0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
122d0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
122e0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
122f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12300 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
12310 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
12320 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
12330 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
12340 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
12350 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
12360 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
12370 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12380 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12390 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
123a0 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
123b0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
123c0 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
123d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
123e0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
123f0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
12400 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
12410 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
12420 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
12430 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
12440 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
12450 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12460 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
12470 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
12480 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
12490 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
124a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
124b0 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
124c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
124d0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
124e0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
124f0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
12500 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12510 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12520 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12530 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12540 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12550 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12560 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12570 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12580 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
12590 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
125a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
125b0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
125c0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
125d0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
125e0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
125f0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12610 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12620 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12630 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
12640 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12650 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12660 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12670 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
12680 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12690 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
126a0 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
126b0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
126c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
126d0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
126e0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
126f0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12700 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
12710 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
12720 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12730 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12740 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
12750 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12760 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12770 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12780 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12790 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
127a0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
127b0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
127c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
127d0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
127e0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
127f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12800 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
12810 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12820 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12830 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
12840 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12850 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
12860 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
12870 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
12880 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12890 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
128a0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
128b0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
128c0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
128d0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
128e0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
128f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12900 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
12910 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
12920 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
12930 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
12940 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12950 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
12960 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12970 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
12980 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
12990 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
129a0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
129b0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
129c0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
129d0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
129e0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
129f0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
12a00 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
12a10 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12a20 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12a30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12a40 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
12a50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
12a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12a70 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
12a80 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
12a90 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
12aa0 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
12ab0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
12ac0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
12ad0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
12ae0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
12af0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12b00 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
12b10 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
12b20 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
12b30 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
12b40 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
12b50 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
12b60 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
12b70 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
12b80 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
12b90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
12ba0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
12bb0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
12bc0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
12bd0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
12be0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
12bf0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
12c00 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
12c10 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
12c20 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
12c30 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12c40 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
12c50 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
12c60 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
12c70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
12c80 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
12c90 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
12ca0 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
12cb0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12cc0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
12cd0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
12ce0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12d00 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
12d10 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12d20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12d30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12d40 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
12d50 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12d60 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12d70 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
12d80 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
12d90 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
12da0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12db0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
12dc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12dd0 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
12de0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
12df0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
12e00 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
12e10 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
12e20 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
12e30 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
12e40 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
12e50 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
12e60 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
12e70 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
12e80 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
12e90 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
12ea0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12eb0 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
12ec0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
12ed0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
12ee0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
12ef0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
12f00 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
12f10 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
12f20 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
12f30 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
12f40 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
12f50 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
12f60 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
12f70 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
12f80 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
12f90 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
12fa0 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
12fb0 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
12fc0 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
12fd0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12fe0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
12ff0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
13000 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13010 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
13020 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13030 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
13040 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
13050 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
13060 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
13070 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
13080 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
13090 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
130a0 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
130b0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
130c0 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
130d0 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
130e0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
130f0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
13100 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
13110 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
13120 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
13130 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13140 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
13150 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
13160 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
13170 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
13180 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
13190 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
131a0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
131b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
131c0 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
131d0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
131e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
131f0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 61 20 6d  CACHE option a m
13200 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68  emory pool.** th
13210 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
13220 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  e for the databa
13230 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
13240 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
13250 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
13260 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
13270 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
13280 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61  tion option is a
13290 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70   no-op if an app
132a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
132b0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
132c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
132d0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
132e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
132f0 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68  PCACHE2]..** ^Th
13300 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13310 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13320 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13330 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
13340 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
13350 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29  ed memory (pMem)
13360 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
13370 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69  ch page cache li
13380 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  ne (sz),.** and 
13390 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61  the number of ca
133a0 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a  che lines (N)..*
133b0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
133c0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
133d0 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
133e0 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
133f0 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
13400 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
13410 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
13420 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
13430 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
13440 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
13450 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
13460 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
13470 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
13480 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
13490 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c  mined using [SQL
134a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
134b0 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74  E_HDRSZ]..** ^It
134c0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
134d0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
134e0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
134f0 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
13500 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
13510 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
13520 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72    The pMem.** ar
13530 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65  gument must be e
13540 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
13550 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65  nter or a pointe
13560 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  r to an 8-byte.*
13570 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  * aligned block 
13580 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  of memory of at 
13590 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
135a0 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73  , otherwise.** s
135b0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
135c0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
135d0 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69  .** ^When pMem i
135e0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
135f0 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74  te will strive t
13600 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  o use the memory
13610 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20   provided.** to 
13620 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63  satisfy page cac
13630 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e  he needs, fallin
13640 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74  g back to [sqlit
13650 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a  e3_malloc()] if.
13660 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20  ** a page cache 
13670 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74  line is larger t
13680 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20  han sz bytes or 
13690 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d  if all of the pM
136a0 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  em buffer.** is 
136b0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49  exhausted..** ^I
136c0 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61  f pMem is NULL a
136d0 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  nd N is non-zero
136e0 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61  , then each data
136f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
13700 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69  ** does an initi
13710 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69  al bulk allocati
13720 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  on for page cach
13730 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d  e memory.** from
13740 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13750 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66  ()] sufficient f
13760 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73  or N cache lines
13770 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
13780 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34  e or.** of -1024
13790 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73  *N bytes if N is
137a0 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66   negative, . ^If
137b0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
137c0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
137d0 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
137e0 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
137f0 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61  ed by the initia
13800 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  l.** allocation,
13810 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65   then SQLite goe
13820 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
13830 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65  lloc()] separate
13840 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61  ly for each.** a
13850 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20  dditional cache 
13860 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  line. </dd>.**.*
13870 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13880 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
13890 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
138a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
138b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
138c0 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
138d0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
138e0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
138f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
13900 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
13910 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
13920 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
13930 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
13940 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
13950 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
13960 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
13970 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
13980 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
13990 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
139a0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
139b0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
139c0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
139d0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
139e0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
139f0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
13a00 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
13a10 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
13a20 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
13a30 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
13a40 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
13a50 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
13a60 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
13a70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
13a80 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
13a90 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
13aa0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
13ab0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
13ac0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
13ad0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
13ae0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13af0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
13b00 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
13b10 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
13b20 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
13b30 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
13b40 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
13b50 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
13b60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13b70 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
13b80 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
13b90 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
13ba0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
13bb0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
13bc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13bd0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
13be0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
13bf0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
13c00 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
13c10 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
13c20 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
13c30 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
13c40 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
13c50 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
13c60 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
13c70 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13c80 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
13c90 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
13ca0 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
13cb0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
13cc0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
13cd0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
13ce0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
13cf0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
13d00 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
13d10 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
13d20 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
13d30 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
13d40 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
13d50 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
13d60 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
13d70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13d80 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
13d90 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13da0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13db0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13dc0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
13dd0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13de0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13df0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
13e00 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13e10 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13e20 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13e30 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
13e40 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
13e50 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
13e60 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
13e70 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
13e80 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
13e90 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
13ea0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
13eb0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
13ec0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
13ed0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
13ee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13ef0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13f00 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
13f10 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
13f20 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
13f30 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
13f40 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
13f50 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
13f60 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
13f70 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13f80 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
13f90 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
13fa0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
13fb0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
13fc0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
13fd0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
13fe0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
13ff0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14000 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14010 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
14020 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14030 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
14040 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14050 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14060 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14070 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
14080 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
14090 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
140a0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
140b0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
140c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
140d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
140e0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
140f0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14100 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14110 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14120 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
14130 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
14140 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
14150 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
14160 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
14170 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
14180 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
14190 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
141a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
141b0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
141c0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
141d0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
141e0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
141f0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
14200 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
14210 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
14220 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
14230 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
14240 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
14250 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
14260 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
14270 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14280 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14290 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
142a0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
142b0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
142c0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
142d0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
142e0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
142f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14300 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
14310 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14320 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
14330 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14340 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14350 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14360 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14370 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14380 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
14390 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
143a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
143b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
143c0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
143d0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
143e0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
143f0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
14400 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
14410 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
14420 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
14430 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
14440 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14450 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
14460 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
14470 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
14480 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
14490 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
144a0 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
144b0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
144c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
144d0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
144e0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
144f0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
14500 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
14510 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
14520 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
14530 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
14540 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
14550 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
14560 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
14570 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
14580 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
14590 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
145a0 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
145b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
145c0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
145d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
145e0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
145f0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14600 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14610 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14620 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14630 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
14640 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
14650 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14660 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14670 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
14680 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
14690 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
146a0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
146b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
146c0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
146d0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
146e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
146f0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14700 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
14710 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14720 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
14730 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14740 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
14750 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14760 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14770 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14780 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14790 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
147a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
147b0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
147c0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
147d0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
147e0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
147f0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
14800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
14810 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
14820 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
14830 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
14840 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
14850 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
14860 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
14870 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14880 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
14890 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
148a0 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
148b0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
148c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
148d0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
148e0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
148f0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
14900 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
14910 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
14920 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
14930 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
14940 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
14950 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
14960 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
14970 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
14980 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
14990 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
149a0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
149b0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
149c0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
149d0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
149e0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
149f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
14a00 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
14a10 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
14a20 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
14a30 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
14a40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14a50 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
14a60 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
14a70 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
14a80 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14a90 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
14aa0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
14ab0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
14ac0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
14ad0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
14ae0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
14af0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
14b00 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
14b10 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
14b20 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14b30 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
14b40 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
14b50 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
14b60 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
14b70 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
14b80 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
14b90 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
14ba0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
14bb0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
14bc0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
14bd0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
14be0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
14bf0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
14c00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
14c10 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
14c20 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
14c30 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
14c40 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
14c50 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
14c60 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
14c70 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
14c80 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
14c90 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
14ca0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
14cb0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
14cc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14cd0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14ce0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
14cf0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
14d00 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14d10 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
14d20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14d30 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
14d40 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14d50 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
14d60 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14d70 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
14d80 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
14d90 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
14da0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
14db0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
14dc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
14dd0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
14de0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14df0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
14e00 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
14e10 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
14e20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
14e30 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
14e40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
14e50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
14e60 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
14e70 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
14e80 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
14e90 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
14ea0 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
14eb0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
14ec0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
14ed0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
14ee0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
14ef0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
14f00 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
14f10 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
14f20 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
14f30 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
14f40 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
14f50 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
14f60 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
14f70 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
14f80 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
14f90 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
14fa0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
14fb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
14fc0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
14fd0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
14fe0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
14ff0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
15000 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
15010 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
15020 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
15030 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
15040 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
15050 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
15060 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15070 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15080 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15090 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
150a0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
150b0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
150c0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
150d0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
150e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
150f0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
15100 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
15110 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
15120 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
15130 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
15140 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
15150 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
15160 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
15170 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
15180 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
15190 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
151a0 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
151b0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
151c0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
151d0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
151e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
151f0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
15200 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
15210 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
15220 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
15230 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
15240 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
15250 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15260 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15270 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
15280 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
15290 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
152a0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
152b0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
152c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
152d0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
152e0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
152f0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
15300 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
15310 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
15320 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
15330 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
15340 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
15350 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
15360 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
15370 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
15380 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
15390 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
153a0 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
153b0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
153c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
153d0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
153e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
153f0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
15400 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
15410 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
15420 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
15430 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
15440 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
15450 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
15460 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
15470 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
15480 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
15490 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
154a0 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
154b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
154c0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
154d0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
154e0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
154f0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
15500 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
15510 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
15520 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
15530 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
15540 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15550 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
15560 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15570 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
15580 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
15590 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
155a0 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
155b0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
155c0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
155d0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
155e0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
155f0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
15600 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
15610 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
15620 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
15630 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
15640 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15650 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
15660 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15670 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
15680 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15690 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
156a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
156b0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
156c0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
156d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
156e0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
156f0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
15700 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
15710 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
15720 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
15730 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15740 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
15750 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
15760 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
15770 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
15780 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
15790 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
157a0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
157b0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
157c0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
157d0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
157e0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
157f0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
15800 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
15810 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15820 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
15830 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
15840 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
15850 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
15860 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
15870 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
15880 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
15890 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
158a0 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
158b0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
158c0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
158d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
158e0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
158f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15900 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
15910 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
15920 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
15930 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
15940 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
15950 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
15960 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
15970 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
15980 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
15990 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
159a0 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
159b0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
159c0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
159d0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
159e0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
159f0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
15a00 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
15a10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15a20 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
15a30 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
15a40 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
15a50 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
15a60 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
15a70 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
15a80 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
15a90 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
15aa0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
15ab0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
15ac0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
15ad0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
15ae0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
15af0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
15b00 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
15b10 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
15b20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15b30 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
15b40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15b50 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
15b60 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
15b70 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
15b80 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
15b90 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
15ba0 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
15bb0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
15bc0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
15bd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15be0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
15bf0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15c00 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15c10 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
15c20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15c30 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
15c40 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
15c50 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
15c60 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
15c70 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
15c80 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
15c90 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
15ca0 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
15cb0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
15cc0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15cd0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
15ce0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
15cf0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
15d00 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
15d10 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
15d20 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
15d30 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
15d40 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15d50 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
15d60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15d70 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
15d80 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
15d90 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
15da0 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
15db0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
15dc0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
15dd0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15de0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
15df0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
15e00 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
15e10 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
15e20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
15e30 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
15e40 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
15e50 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
15e60 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
15e70 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
15e80 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
15e90 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
15ea0 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
15eb0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
15ec0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
15ed0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15ee0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
15ef0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
15f00 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
15f10 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
15f20 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
15f30 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15f40 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
15f50 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
15f60 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
15f70 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
15f80 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
15f90 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
15fa0 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
15fb0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
15fc0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
15fd0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
15fe0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
15ff0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
16000 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16010 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
16020 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
16030 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
16040 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
16050 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
16060 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
16070 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
16080 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
16090 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
160a0 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
160b0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
160c0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
160d0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
160e0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
160f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
16100 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
16110 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
16120 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  alue..** </dl>.*
16130 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16140 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
16150 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
16160 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16170 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
16180 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
16190 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
161a0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
161b0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
161c0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
161d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
161e0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
161f0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16200 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16220 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
16230 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
16240 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
16250 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16260 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
16270 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
16280 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
16290 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
162a0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
162b0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
162c0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
162d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
162e0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
162f0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
16300 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
16310 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16320 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
16330 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
16340 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
16350 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16360 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
16370 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
16380 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16390 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
163a0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
163b0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
163c0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
163d0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
163e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
163f0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
16400 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
16410 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
16420 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16430 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
16440 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
16450 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16460 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
16470 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16480 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16490 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
164a0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
164b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
164c0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
164d0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
164e0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
164f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
16500 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
16510 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
16520 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16530 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
16540 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
16550 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
16560 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16570 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
16580 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
16590 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
165a0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
165b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
165c0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
165d0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
165e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
165f0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
16600 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
16610 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
16620 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16630 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
16640 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
16650 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
16660 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16670 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16680 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
16690 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
166a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
166b0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
166c0 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
166d0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
166e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
166f0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
16700 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
16710 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
16720 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ma */../*.** CAP
16730 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
16740 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
16750 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
16760 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
16770 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
16780 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
16790 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
167a0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
167b0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
167c0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
167d0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
167e0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
167f0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
16800 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
16810 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
16820 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
16830 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
16840 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
16850 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
16860 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
16870 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
16880 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
16890 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
168a0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
168b0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
168c0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
168d0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
168e0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
168f0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
16900 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
16910 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
16920 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
16930 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
16940 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
16950 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
16960 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16970 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
16980 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
16990 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
169a0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
169b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
169c0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
169d0 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
169e0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
169f0 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
16a00 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
16a10 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
16a20 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
16a30 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
16a40 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
16a50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16a60 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
16a70 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
16a80 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
16a90 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
16aa0 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
16ab0 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
16ac0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
16ad0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
16ae0 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
16af0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
16b00 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
16b10 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
16b20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
16b30 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
16b40 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
16b50 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
16b60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
16b70 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
16b80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
16b90 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
16ba0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
16bb0 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
16bc0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
16bd0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
16be0 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
16bf0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
16c00 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
16c10 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
16c20 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
16c30 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
16c40 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
16c50 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
16c60 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
16c70 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
16c80 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
16c90 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
16ca0 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
16cb0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
16cc0 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
16cd0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
16ce0 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
16cf0 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
16d00 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
16d10 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
16d20 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
16d30 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
16d40 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
16d50 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
16d60 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
16d70 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
16d80 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
16d90 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
16da0 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
16db0 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
16dc0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
16dd0 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
16de0 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
16df0 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
16e00 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
16e10 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
16e20 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
16e30 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
16e40 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
16e50 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
16e60 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
16e70 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
16e80 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
16e90 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
16ea0 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
16eb0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
16ec0 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
16ed0 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
16ee0 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
16ef0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
16f00 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16f10 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
16f20 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
16f30 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
16f40 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
16f50 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
16f60 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
16f70 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
16f80 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
16f90 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
16fa0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
16fb0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16fc0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
16fd0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
16fe0 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
16ff0 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
17000 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
17010 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
17020 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
17030 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
17040 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
17050 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17060 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
17070 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
17080 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
17090 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
170a0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
170b0 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
170c0 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
170d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
170e0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
170f0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
17100 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
17110 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
17120 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
17130 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
17140 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
17150 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
17160 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17170 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
17180 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
17190 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
171a0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
171b0 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
171c0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
171d0 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
171e0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
171f0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17200 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
17210 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17220 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
17230 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
17240 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
17250 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
17260 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
17270 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
17280 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
17290 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
172a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
172b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
172c0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
172d0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
172e0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
172f0 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
17300 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
17310 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
17320 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
17330 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
17340 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
17350 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17360 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17370 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
17380 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
17390 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
173a0 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
173b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
173c0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
173d0 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f  DE       1001  /
173e0 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
173f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17400 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17410 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20  E_FKEY     1002 
17420 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
17430 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17440 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
17450 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a  RIGGER  1003  /*
17460 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
17470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
17480 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
17490 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
174a0 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44   Codes.** METHOD
174b0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
174c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
174d0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
174e0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
174f0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
17500 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
17510 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
17520 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
17530 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
17540 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
17550 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
17560 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
17570 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
17580 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
17590 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
175a0 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
175b0 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
175c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
175d0 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
175e0 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  owid.** METHOD: 
175f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45  sqlite3.**.** ^E
17600 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73  ach entry in mos
17610 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20  t SQLite tables 
17620 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54  (except for [WIT
17630 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
17640 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69  es).** has a uni
17650 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
17660 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
17670 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
17680 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
17690 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
176a0 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
176b0 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
176c0 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
176d0 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
176e0 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
176f0 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
17700 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
17710 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
17720 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
17730 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
17740 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
17750 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
17760 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
17770 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
17780 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
17790 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
177a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
177b0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
177c0 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66  _rowid(D) interf
177d0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
177e0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a  [rowid] of the .
177f0 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  ** most recent s
17800 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
17810 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20  T] into a rowid 
17820 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61  table or [virtua
17830 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64  l table].** on d
17840 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17850 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74  on D..** ^Insert
17860 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20  s into [WITHOUT 
17870 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72  ROWID] tables ar
17880 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a  e not recorded..
17890 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  ** ^If no succes
178a0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69  sful [INSERT]s i
178b0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
178c0 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
178d0 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61  curred on the da
178e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
178f0 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71  n D, .** then sq
17900 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17910 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
17920 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
17930 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
17940 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
17950 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
17960 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
17970 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
17980 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
17990 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
179a0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
179b0 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
179c0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
179d0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
179e0 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
179f0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
17a00 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
17a10 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
17a20 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
17a30 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17a40 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
17a50 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
17a60 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
17a70 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
17a80 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
17a90 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
17aa0 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
17ab0 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
17ac0 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
17ad0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17ae0 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
17af0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17b00 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
17b10 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
17b20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
17b30 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
17b40 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
17b50 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
17b60 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
17b70 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
17b80 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
17b90 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
17ba0 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
17bb0 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
17bc0 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
17bd0 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
17be0 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
17bf0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
17c00 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
17c10 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
17c20 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
17c30 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
17c40 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
17c50 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
17c60 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
17c70 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
17c80 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
17c90 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
17ca0 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
17cb0 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
17cc0 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
17cd0 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
17ce0 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
17cf0 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
17d00 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
17d10 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
17d20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
17d30 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
17d40 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
17d50 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
17d60 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
17d70 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
17d80 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
17d90 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
17da0 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
17db0 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
17dc0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
17dd0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
17de0 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
17df0 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
17e00 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
17e10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17e20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
17e30 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17e40 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
17e50 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
17e60 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
17e70 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
17e80 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
17e90 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17ea0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
17eb0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17ec0 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
17ed0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
17ee0 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
17ef0 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
17f00 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
17f10 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
17f20 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
17f30 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17f40 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
17f50 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
17f60 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
17f70 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
17f80 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
17f90 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
17fa0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
17fb0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
17fc0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
17fd0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
17fe0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
17ff0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
18000 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
18010 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
18020 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
18030 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
18040 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
18050 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
18060 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
18070 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
18080 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
18090 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
180a0 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
180b0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
180c0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
180d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
180e0 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
180f0 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
18100 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
18110 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
18120 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
18130 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
18140 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
18150 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
18160 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
18170 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
18180 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
18190 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
181a0 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
181b0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
181c0 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
181d0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
181e0 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
181f0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
18200 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
18210 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
18220 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
18230 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
18240 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
18250 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
18260 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
18270 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
18280 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
18290 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
182a0 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
182b0 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
182c0 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
182d0 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
182e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
182f0 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
18300 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
18310 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
18320 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
18330 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
18340 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
18350 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
18360 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
18370 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
18380 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
18390 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
183a0 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
183b0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
183c0 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
183d0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
183e0 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
183f0 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
18400 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
18410 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
18420 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
18430 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18440 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
18450 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18460 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
18470 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
18480 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
18490 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
184a0 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
184b0 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
184c0 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
184d0 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
184e0 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
184f0 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
18500 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
18510 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
18520 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
18530 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
18540 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
18550 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
18560 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
18570 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
18580 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
18590 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
185a0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
185b0 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
185c0 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
185d0 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
185e0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
185f0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
18600 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
18610 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
18620 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
18630 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
18640 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
18650 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
18660 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
18670 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
18680 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
18690 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
186a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
186b0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
186c0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
186d0 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
186e0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
186f0 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
18700 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
18710 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
18720 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
18730 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
18740 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
18750 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
18760 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
18770 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
18780 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
18790 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
187a0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
187b0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
187c0 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
187d0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
187e0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
187f0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
18800 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
18810 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
18820 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
18830 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
18840 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
18850 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
18860 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
18870 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
18880 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
18890 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
188a0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
188b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
188c0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
188d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
188e0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
188f0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
18900 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
18910 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
18920 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
18930 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
18940 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
18950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18960 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
18970 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
18980 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
18990 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
189a0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
189b0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
189c0 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
189d0 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
189e0 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
189f0 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
18a00 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
18a10 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
18a20 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
18a30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18a40 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
18a50 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
18a60 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
18a70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
18a80 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
18a90 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
18aa0 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
18ab0 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
18ac0 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
18ad0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
18ae0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
18af0 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
18b00 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
18b10 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
18b20 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
18b30 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
18b40 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
18b50 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
18b60 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
18b70 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
18b80 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
18b90 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
18ba0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
18bb0 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
18bc0 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
18bd0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
18be0 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
18bf0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
18c00 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
18c10 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
18c20 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
18c30 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
18c40 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
18c50 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
18c60 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
18c70 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
18c80 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
18c90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18ca0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
18cb0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
18cc0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
18cd0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
18ce0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
18cf0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
18d00 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
18d10 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
18d20 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18d30 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18d40 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
18d50 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
18d60 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45  ning Query.** ME
18d70 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
18d80 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
18d90 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
18da0 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
18db0 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
18dc0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
18dd0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
18de0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
18df0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
18e00 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
18e10 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
18e20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
18e30 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
18e40 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
18e50 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
18e60 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
18e70 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
18e80 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
18e90 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
18ea0 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
18eb0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
18ec0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
18ed0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
18ee0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
18ef0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
18f00 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
18f10 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
18f20 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
18f30 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
18f40 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
18f50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
18f60 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
18f70 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
18f80 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
18f90 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18fa0 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
18fb0 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
18fc0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
18fd0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
18fe0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
18ff0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
19000 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
19010 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
19020 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
19030 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
19040 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
19050 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
19060 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
19070 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
19080 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
19090 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
190a0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
190b0 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
190c0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
190d0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
190e0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
190f0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
19100 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
19110 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
19120 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
19130 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
19140 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
19150 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
19160 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
19170 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
19180 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
19190 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
191a0 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
191b0 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
191c0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
191d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
191e0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
191f0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
19200 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
19210 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
19220 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
19230 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
19240 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
19250 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
19260 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
19270 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
19280 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
19290 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
192a0 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
192b0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
192c0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
192d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
192e0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
192f0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
19300 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
19310 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
19320 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
19330 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
19340 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19350 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
19360 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19370 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
19380 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
19390 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
193a0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
193b0 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
193c0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
193d0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
193e0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
193f0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
19400 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
19410 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
19420 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
19430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
19440 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
19450 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
19460 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
19470 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
19480 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
19490 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
194a0 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
194b0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
194c0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
194d0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
194e0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
194f0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
19500 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
19510 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
19520 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
19530 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
19540 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
19550 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
19560 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
19570 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
19580 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
19590 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
195a0 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
195b0 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
195c0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
195d0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
195e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
195f0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
19600 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
19610 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
19620 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
19630 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
19640 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
19650 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
19660 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
19670 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
19680 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
19690 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
196a0 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
196b0 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
196c0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
196d0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
196e0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
196f0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
19700 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
19710 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
19720 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
19730 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
19740 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
19750 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
19760 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
19770 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
19780 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
19790 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
197a0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
197b0 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
197c0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
197d0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
197e0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
197f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
19800 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
19810 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
19820 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
19830 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
19840 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
19850 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
19860 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
19870 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
19880 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
19890 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
198a0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
198b0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
198c0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
198d0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
198e0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
198f0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
19900 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
19910 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
19920 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
19930 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
19940 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19950 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
19960 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
19970 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
19980 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
19990 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
199a0 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
199b0 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
199c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
199d0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
199e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
199f0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
19a00 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
19a10 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
19a20 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
19a30 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
19a40 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
19a50 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
19a60 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
19a70 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
19a80 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
19a90 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
19aa0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
19ab0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
19ac0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
19ad0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
19ae0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
19af0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
19b00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
19b10 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
19b20 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
19b30 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19b40 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
19b50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19b60 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
19b70 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
19b80 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
19b90 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  rors.** KEYWORDS
19ba0 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  : {busy-handler 
19bb0 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20  callback} {busy 
19bc0 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  handler}.** METH
19bd0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19be0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
19bf0 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
19c00 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
19c10 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
19c20 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
19c30 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
19c40 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
19c50 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
19c60 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
19c70 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
19c80 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
19c90 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
19ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19cb0 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
19cc0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
19cd0 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
19ce0 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
19cf0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
19d00 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
19d10 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
19d20 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
19d30 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
19d40 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
19d50 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
19d60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
19d70 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
19d80 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
19d90 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
19da0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
19db0 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
19dc0 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
19dd0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
19de0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
19df0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
19e00 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
19e10 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
19e20 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
19e30 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
19e40 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
19e50 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
19e60 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
19e70 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
19e80 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
19e90 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
19ea0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19eb0 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
19ec0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
19ed0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19ee0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
19ef0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
19f00 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
19f10 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
19f20 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69  en invoked previ
19f30 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61  ously for the sa
19f40 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
19f50 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
19f60 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
19f70 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
19f80 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
19f90 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
19fa0 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
19fb0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
19fc0 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
19fd0 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
19fe0 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
19ff0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1a000 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1a010 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1a020 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1a030 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
1a040 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
1a050 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1a060 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1a070 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1a080 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1a090 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1a0a0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1a0b0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1a0c0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1a0d0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1a0e0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1a0f0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1a100 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1a110 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1a120 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1a130 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1a140 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1a150 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1a160 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
1a170 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
1a180 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1a190 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1a1a0 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1a1b0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1a1c0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1a1d0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1a1e0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1a1f0 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1a200 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1a210 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1a220 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1a230 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1a240 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1a250 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1a260 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1a270 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1a280 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1a290 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1a2a0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1a2b0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1a2c0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1a2d0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1a2e0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1a2f0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1a300 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1a310 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1a320 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1a330 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1a340 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1a350 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1a360 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1a370 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1a380 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1a390 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1a3a0 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1a3b0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1a3c0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1a3d0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1a3e0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1a3f0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1a400 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1a410 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1a420 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1a430 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
1a440 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1a450 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1a460 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
1a470 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
1a480 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1a490 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
1a4a0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
1a4b0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
1a4c0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
1a4d0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
1a4e0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1a4f0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1a500 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
1a510 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
1a520 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
1a530 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
1a540 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
1a550 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
1a560 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
1a570 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1a580 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
1a590 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
1a5a0 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
1a5b0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
1a5c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1a5d0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1a5e0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1a5f0 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
1a600 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
1a610 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
1a620 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
1a630 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1a640 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1a650 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1a660 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1a670 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1a680 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1a690 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1a6a0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1a6b0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1a6c0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1a6d0 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
1a6e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a6f0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
1a700 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
1a710 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1a720 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1a730 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45  sy Timeout.** ME
1a740 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1a750 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1a760 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1a770 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1a780 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1a790 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1a7a0 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1a7b0 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1a7c0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1a7d0 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1a7e0 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1a7f0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1a800 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1a810 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1a820 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1a830 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1a840 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1a850 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1a860 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1a870 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1a880 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1a890 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1a8a0 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1a8b0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1a8c0 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1a8d0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1a8e0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1a8f0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1a900 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1a910 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1a920 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1a930 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1a940 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1a950 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1a960 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1a970 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a980 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1a990 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1a9a0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1a9b0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1a9c0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1a9d0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a9e0 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1a9f0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1aa00 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1aa10 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1aa20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1aa30 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1aa40 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1aa50 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
1aa60 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1aa70 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1aa80 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1aa90 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1aaa0 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1aab0 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1aac0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1aad0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
1aae0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1aaf0 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
1ab00 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
1ab10 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1ab20 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
1ab30 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
1ab40 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
1ab50 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
1ab60 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
1ab70 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
1ab80 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
1ab90 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
1aba0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1abb0 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
1abc0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
1abd0 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
1abe0 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
1abf0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
1ac00 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
1ac10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
1ac20 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
1ac30 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
1ac40 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
1ac50 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
1ac60 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
1ac70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
1ac80 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
1ac90 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
1aca0 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
1acb0 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
1acc0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
1acd0 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
1ace0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1acf0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
1ad00 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1ad10 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
1ad20 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
1ad30 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1ad40 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
1ad50 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
1ad60 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
1ad70 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
1ad80 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
1ad90 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
1ada0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1adb0 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
1adc0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
1add0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
1ade0 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
1adf0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
1ae00 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
1ae10 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
1ae20 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
1ae30 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
1ae40 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
1ae50 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
1ae60 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1ae70 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
1ae80 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
1ae90 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
1aea0 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
1aeb0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1aec0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
1aed0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
1aee0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1aef0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
1af00 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
1af10 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
1af20 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
1af30 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
1af40 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
1af50 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
1af60 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1af70 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
1af80 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
1af90 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
1afa0 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
1afb0 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
1afc0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
1afd0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1afe0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1aff0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
1b000 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
1b010 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
1b020 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1b030 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
1b040 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
1b050 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
1b060 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
1b070 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
1b080 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b090 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1b0a0 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
1b0b0 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
1b0c0 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
1b0d0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
1b0e0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
1b0f0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
1b100 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
1b110 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
1b120 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
1b130 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
1b140 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
1b150 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
1b160 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1b170 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1b180 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
1b190 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
1b1a0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b1b0 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
1b1c0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b1d0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1b1e0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1b1f0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1b200 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1b210 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1b220 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1b230 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b240 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1b250 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b260 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1b270 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b280 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1b290 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1b2a0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1b2b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1b2c0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1b2d0 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1b2e0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1b2f0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1b300 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1b310 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1b320 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1b330 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1b340 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1b350 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1b360 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1b370 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1b380 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1b390 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1b3a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1b3b0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1b3c0 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1b3d0 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1b3e0 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1b3f0 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1b400 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1b410 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1b420 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1b430 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1b440 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1b450 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1b460 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1b470 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1b480 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1b490 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1b4a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1b4b0 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1b4c0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1b4d0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1b4e0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1b4f0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1b500 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1b510 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1b520 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1b530 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1b540 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1b550 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1b560 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1b570 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1b580 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1b590 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1b5a0 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1b5b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b5c0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1b5d0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1b5e0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1b5f0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1b600 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1b610 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1b620 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1b630 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1b640 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1b650 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1b660 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
1b670 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
1b680 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
1b690 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
1b6a0 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
1b6b0 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
1b6c0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
1b6d0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1b6e0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
1b6f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1b700 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
1b710 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b720 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1b730 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1b740 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1b750 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1b760 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1b770 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1b780 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1b790 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1b7a0 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1b7b0 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1b7c0 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1b7d0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1b7e0 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1b7f0 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1b800 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1b810 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1b820 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1b830 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1b840 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1b850 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1b860 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1b870 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1b880 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1b890 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1b8a0 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1b8b0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1b8c0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1b8d0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b8e0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1b8f0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1b900 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1b910 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1b920 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1b930 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65   library..** The
1b940 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65  se routines unde
1b950 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74  rstand most of t
1b960 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f  he common K&R fo
1b970 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1b980 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61  ,.** plus some a
1b990 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74  dditional non-st
1b9a0 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20  andard formats, 
1b9b0 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a  detailed below..
1b9c0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d  ** Note that som
1b9d0 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62  e of the more ob
1b9e0 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67  scure formatting
1b9f0 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65   options from re
1ba00 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72  cent.** C-librar
1ba10 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20  y standards are 
1ba20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69  omitted from thi
1ba30 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1ba40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ba50 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
1ba60 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
1ba70 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
1ba80 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
1ba90 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
1baa0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1bab0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1bac0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
1bad0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
1bae0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
1baf0 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
1bb00 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
1bb10 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
1bb20 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
1bb30 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
1bb40 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
1bb50 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
1bb60 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1bb70 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
1bb80 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
1bb90 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
1bba0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1bbb0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
1bbc0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
1bbd0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
1bbe0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
1bbf0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1bc00 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
1bc10 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
1bc20 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
1bc30 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
1bc40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
1bc50 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
1bc60 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
1bc70 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
1bc80 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
1bc90 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1bca0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
1bcb0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
1bcc0 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
1bcd0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
1bce0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
1bcf0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
1bd00 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
1bd10 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
1bd20 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1bd30 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
1bd40 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
1bd50 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
1bd60 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1bd70 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
1bd80 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
1bd90 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
1bda0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
1bdb0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
1bdc0 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
1bdd0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
1bde0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1bdf0 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
1be00 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
1be10 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
1be20 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
1be30 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
1be40 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
1be50 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1be60 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
1be70 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
1be80 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
1be90 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
1bea0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
1beb0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
1bec0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1bed0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
1bee0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
1bef0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
1bf00 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
1bf10 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1bf20 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
1bf30 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
1bf40 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
1bf50 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
1bf60 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
1bf70 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
1bf80 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
1bf90 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
1bfa0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
1bfb0 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
1bfc0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
1bfd0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1bfe0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
1bff0 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
1c000 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1c010 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
1c020 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
1c030 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
1c040 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
1c050 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
1c060 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
1c070 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
1c080 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
1c090 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
1c0a0 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
1c0b0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1c0c0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
1c0d0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
1c0e0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
1c0f0 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22  ", "%w" and "%z"
1c100 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1c110 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1c120 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1c130 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1c140 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1c150 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1c160 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1c170 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1c180 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1c190 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1c1a0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1c1b0 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1c1c0 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1c1d0 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1c1e0 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1c1f0 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1c200 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1c210 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1c220 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1c230 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1c240 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1c250 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1c260 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1c270 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1c280 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1c290 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1c2a0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c2b0 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1c2c0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1c2d0 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1c2e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c2f0 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1c300 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1c310 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1c320 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1c330 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c340 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1c350 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1c360 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1c370 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1c380 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1c390 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1c3a0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1c3b0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1c3c0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1c3d0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1c3e0 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1c3f0 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1c400 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1c410 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1c420 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1c430 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1c440 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1c450 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1c460 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c470 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1c480 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1c490 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1c4a0 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1c4b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c4c0 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1c4d0 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1c4e0 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1c4f0 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1c500 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1c510 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1c520 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1c530 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c540 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1c550 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1c560 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1c570 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c580 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1c590 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1c5a0 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1c5b0 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1c5c0 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1c5d0 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1c5e0 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1c5f0 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1c600 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1c610 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1c620 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1c630 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1c640 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1c650 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1c660 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1c670 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1c680 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1c690 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1c6a0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1c6b0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1c6c0 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1c6d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1c6e0 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1c6f0 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1c700 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1c710 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1c720 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1c730 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1c740 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1c750 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1c760 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1c770 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1c780 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1c790 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1c7a0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1c7b0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1c7c0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1c7d0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1c7e0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1c7f0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1c800 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1c810 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1c820 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1c830 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1c840 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1c850 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1c860 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1c870 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20  *.** ^(The "%w" 
1c880 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1c890 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65  n is like "%q" e
1c8a0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78  xcept that it ex
1c8b0 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63  pects to.** be c
1c8c0 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20  ontained within 
1c8d0 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e  double-quotes in
1c8e0 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20  stead of single 
1c8f0 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a  quotes, and it.*
1c900 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f  * escapes the do
1c910 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61  uble-quote chara
1c920 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  cter instead of 
1c930 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65  the single-quote
1c940 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e  .** character.)^
1c950 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61    The "%w" forma
1c960 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1c970 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66  intended for saf
1c980 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a  ely inserting.**
1c990 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
1c9a0 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63  n names into a c
1c9b0 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73  onstructed SQL s
1c9c0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
1c9d0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1c9e0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1c9f0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1ca00 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1ca10 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1ca20 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1ca30 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1ca40 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1ca50 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1ca60 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1ca70 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1ca80 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
1ca90 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1caa0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1cab0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1cac0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1cad0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1cae0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
1caf0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1cb00 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1cb10 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
1cb20 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1cb30 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1cb40 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1cb50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cb60 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1cb70 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1cb80 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1cb90 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1cba0 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1cbb0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1cbc0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1cbd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1cbe0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1cbf0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1cc00 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1cc10 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1cc20 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1cc30 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1cc40 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1cc50 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1cc60 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1cc70 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1cc80 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1cc90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1cca0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1ccb0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1ccc0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1ccd0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1cce0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1ccf0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1cd00 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1cd10 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1cd20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1cd30 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1cd40 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1cd50 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1cd60 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1cd70 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1cd80 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1cd90 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1cda0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1cdb0 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1cdc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1cdd0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1cde0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1cdf0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1ce00 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1ce10 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1ce20 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1ce30 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1ce40 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1ce50 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1ce60 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1ce70 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1ce80 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1ce90 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1cea0 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1ceb0 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1cec0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1ced0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1cee0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1cef0 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1cf00 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1cf10 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1cf20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1cf30 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1cf40 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1cf50 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1cf60 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1cf70 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1cf80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1cf90 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1cfa0 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1cfb0 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1cfc0 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1cfd0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1cfe0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1cff0 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1d000 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1d010 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1d020 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1d030 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1d040 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1d050 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1d060 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1d070 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1d080 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1d090 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1d0a0 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1d0b0 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1d0c0 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1d0d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1d0e0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1d0f0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1d100 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1d110 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1d120 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d130 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d140 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1d150 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1d160 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1d170 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1d180 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1d190 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1d1a0 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1d1b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d1c0 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1d1d0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1d1e0 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1d1f0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1d200 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1d210 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1d220 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1d230 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1d240 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1d250 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1d260 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1d270 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1d280 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1d290 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1d2a0 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1d2b0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1d2c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1d2d0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1d2e0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1d2f0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1d300 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1d310 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1d320 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1d330 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1d340 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1d350 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1d360 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1d370 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1d380 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1d390 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1d3a0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1d3b0 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1d3c0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1d3d0 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1d3e0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1d3f0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1d400 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1d410 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1d420 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1d430 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1d440 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1d450 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1d460 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1d470 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1d480 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1d490 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1d4a0 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1d4b0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1d4c0 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1d4d0 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1d4e0 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1d4f0 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1d500 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1d510 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1d520 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d530 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1d540 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1d550 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1d560 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1d570 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1d580 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1d590 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1d5a0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1d5b0 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1d5c0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1d5d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d5e0 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1d5f0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1d600 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1d610 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1d620 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1d630 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1d640 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1d650 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1d660 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1d670 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1d680 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1d690 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1d6a0 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1d6b0 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1d6c0 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1d6d0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1d6e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1d6f0 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1d700 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1d710 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1d720 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1d730 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1d740 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1d750 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1d760 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1d770 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1d780 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1d790 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1d7a0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1d7b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1d7c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1d7d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1d7e0 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1d7f0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1d800 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1d810 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1d820 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1d830 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1d840 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1d850 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1d860 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1d870 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1d880 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1d890 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1d8a0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1d8b0 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1d8c0 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1d8d0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1d8e0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1d8f0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1d900 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1d910 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1d920 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1d930 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1d940 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1d950 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1d960 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1d970 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1d980 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1d990 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1d9a0 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1d9b0 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1d9c0 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1d9d0 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1d9e0 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1d9f0 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1da00 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1da10 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1da20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1da30 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1da40 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1da50 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1da60 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1da70 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1da80 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1da90 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1daa0 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1dab0 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1dac0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1dad0 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1dae0 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1daf0 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1db00 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1db10 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1db20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1db30 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1db40 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1db50 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1db60 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1db70 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1db80 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1db90 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1dba0 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1dbb0 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1dbc0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1dbd0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1dbe0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1dbf0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1dc00 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1dc10 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1dc20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1dc30 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1dc40 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1dc50 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1dc60 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1dc70 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1dc80 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1dc90 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1dca0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1dcb0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1dcc0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
1dcd0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1dce0 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
1dcf0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73  lite3_malloc64(s
1dd00 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1dd10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1dd20 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1dd30 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1dd40 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a  _realloc64(void*
1dd50 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
1dd60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1dd70 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c  free(void*);.sql
1dd80 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
1dd90 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
1dda0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ddb0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1ddc0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1ddd0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1dde0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1ddf0 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1de00 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1de10 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1de20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1de30 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1de40 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1de50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1de60 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1de70 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1de80 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1de90 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1dea0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1deb0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1dec0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1ded0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1dee0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1def0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1df00 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1df10 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1df20 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1df30 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1df40 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1df50 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1df60 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1df70 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1df80 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1df90 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1dfa0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1dfb0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1dfc0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1dfd0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1dfe0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1dff0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e000 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1e010 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1e020 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1e030 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1e040 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1e050 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1e060 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1e070 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1e080 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1e090 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1e0a0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1e0b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1e0c0 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1e0d0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1e0e0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1e0f0 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1e100 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1e110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1e120 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1e130 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1e140 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1e150 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e160 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1e170 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1e180 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1e190 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1e1a0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1e1b0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1e1c0 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1e1d0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
1e1e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1e1f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1e200 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
1e210 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1e220 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1e230 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1e240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1e250 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1e260 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1e270 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1e280 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1e290 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1e2a0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1e2b0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1e2c0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1e2d0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1e2e0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1e2f0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1e300 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1e310 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1e320 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1e330 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1e340 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1e350 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1e360 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1e370 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1e380 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1e390 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1e3a0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1e3b0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1e3c0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1e3d0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1e3e0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1e3f0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1e400 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1e410 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1e420 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1e430 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
1e440 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
1e450 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1e460 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
1e470 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
1e480 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
1e490 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
1e4a0 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
1e4b0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
1e4c0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
1e4d0 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
1e4e0 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
1e4f0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1e500 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
1e510 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1e520 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
1e530 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1e540 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1e550 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
1e560 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
1e570 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
1e580 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
1e590 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
1e5a0 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
1e5b0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1e5c0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1e5d0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1e5e0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1e5f0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1e600 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1e610 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
1e620 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1e630 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1e640 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1e650 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1e660 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1e670 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  on Callbacks.** 
1e680 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1e690 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1e6a0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1e6b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e6c0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1e6d0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1e6e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1e6f0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1e700 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1e710 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1e720 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1e730 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1e740 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1e750 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1e760 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1e770 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1e780 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1e790 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1e7a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1e7b0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1e7c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e7d0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1e7e0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1e7f0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1e800 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1e810 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1e820 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1e830 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1e840 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1e850 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1e860 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1e870 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1e880 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1e890 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1e8a0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1e8b0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1e8c0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1e8d0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1e8e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1e8f0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1e900 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1e910 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1e920 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1e930 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1e940 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1e950 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1e960 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1e970 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1e980 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1e990 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1e9a0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1e9b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1e9c0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1e9d0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1e9e0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1e9f0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1ea00 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1ea10 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1ea20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1ea30 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1ea40 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1ea50 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1ea60 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1ea70 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1ea80 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1ea90 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1eaa0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1eab0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1eac0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1ead0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1eae0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1eaf0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1eb00 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1eb10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1eb20 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1eb30 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1eb40 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1eb50 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1eb60 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1eb70 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1eb80 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1eb90 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1eba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1ebb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ebc0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ebd0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1ebe0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1ebf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1ec00 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1ec10 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1ec20 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1ec30 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1ec40 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1ec50 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1ec60 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1ec70 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1ec80 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1ec90 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1eca0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1ecb0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1ecc0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1ecd0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1ece0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1ecf0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1ed00 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1ed10 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1ed20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1ed30 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1ed40 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1ed50 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1ed60 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1ed70 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1ed80 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ed90 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1eda0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1edb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1edc0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1edd0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1ede0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1edf0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1ee00 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1ee10 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1ee20 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1ee30 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1ee40 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1ee50 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1ee60 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1ee70 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1ee80 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1ee90 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1eea0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1eeb0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1eec0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1eed0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1eee0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1eef0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1ef00 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1ef10 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1ef20 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1ef30 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1ef40 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1ef50 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1ef60 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1ef70 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1ef80 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1ef90 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1efa0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1efb0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1efc0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1efd0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1efe0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1eff0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1f000 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1f010 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1f020 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1f030 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1f040 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1f050 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1f060 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1f070 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1f080 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1f090 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1f0a0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1f0b0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1f0c0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1f0d0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1f0e0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1f0f0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1f100 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1f110 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1f120 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1f130 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1f140 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1f150 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1f160 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1f170 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1f180 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1f190 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1f1a0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1f1b0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1f1c0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1f1d0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1f1e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1f1f0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1f200 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1f210 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1f220 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1f230 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1f240 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1f250 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1f260 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1f270 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1f280 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1f290 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1f2a0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1f2b0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1f2c0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1f2d0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1f2e0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1f2f0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1f300 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1f310 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1f320 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1f330 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1f340 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1f350 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1f360 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f370 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1f380 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1f390 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1f3a0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1f3b0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1f3c0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1f3d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1f3e0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1f3f0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1f400 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1f410 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1f420 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1f430 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f440 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1f450 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1f460 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1f470 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1f480 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1f490 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1f4a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1f4b0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1f4c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f4d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1f4e0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1f4f0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1f500 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1f510 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1f520 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1f530 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1f540 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1f550 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f560 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1f570 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1f580 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1f590 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1f5a0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1f5b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f5c0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1f5d0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1f5e0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1f5f0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1f600 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1f610 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1f620 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1f630 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1f640 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1f650 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1f660 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1f670 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f680 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1f690 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1f6a0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1f6b0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1f6c0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1f6d0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1f6e0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1f6f0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1f700 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1f710 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1f720 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1f730 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1f740 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1f750 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1f760 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f770 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1f780 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1f790 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1f7a0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1f7b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1f7c0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1f7d0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1f7e0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1f7f0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1f800 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1f810 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1f820 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1f830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1f840 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1f850 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1f860 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1f870 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1f880 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1f890 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1f8a0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1f8b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1f8c0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1f8d0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1f8e0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1f8f0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1f900 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1f910 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1f920 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1f930 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1f940 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1f950 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1f960 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1f970 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1f980 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1f990 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1f9a0 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f  so used as a [co
1f9b0 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f  nflict resolutio
1f9c0 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72  n mode].** retur
1f9d0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ned from the [sq
1f9e0 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
1f9f0 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
1fa00 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
1fa10 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
1fa20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
1fa30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
1fa40 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
1fa50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
1fa60 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
1fa70 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
1fa80 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
1fa90 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
1faa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1fab0 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
1fac0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1fad0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1fae0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
1faf0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
1fb00 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1fb10 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
1fb20 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
1fb30 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
1fb40 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
1fb50 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
1fb60 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
1fb70 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1fb80 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
1fb90 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1fba0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
1fbb0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
1fbc0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
1fbd0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
1fbe0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
1fbf0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1fc00 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
1fc10 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
1fc20 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
1fc30 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
1fc40 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
1fc50 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
1fc60 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
1fc70 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
1fc80 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
1fc90 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
1fca0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1fcb0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
1fcc0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
1fcd0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
1fce0 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
1fcf0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1fd00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1fd10 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
1fd20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
1fd30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fd40 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
1fd50 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1fd60 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
1fd70 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
1fd80 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
1fd90 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
1fda0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1fdb0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
1fdc0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1fdd0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
1fde0 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
1fdf0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1fe00 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
1fe10 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
1fe20 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
1fe30 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
1fe40 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
1fe50 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
1fe60 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
1fe70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fe80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fe90 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
1fea0 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
1feb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fec0 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
1fed0 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
1fee0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1fef0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1ff00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ff10 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
1ff20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
1ff30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1ff40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ff50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ff60 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
1ff70 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
1ff80 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1ff90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ffa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1ffb0 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
1ffc0 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
1ffd0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1ffe0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fff0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
20000 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
20010 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
20020 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
20030 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20040 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
20050 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
20060 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
20070 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
20080 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20090 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
200a0 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
200b0 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
200c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
200d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
200e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
200f0 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
20100 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
20110 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
20120 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20130 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
20140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20150 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
20160 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20170 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20180 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
20190 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
201a0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
201b0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
201c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
201d0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
201e0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
201f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20200 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20210 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20220 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
20230 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
20240 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
20250 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20260 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20270 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
20280 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
20290 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
202a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
202b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
202c0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
202d0 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
202e0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
202f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
20300 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20310 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
20320 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
20330 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
20340 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20350 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20360 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
20370 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
20380 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
20390 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
203a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
203b0 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
203c0 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
203d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
203e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
203f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20400 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
20410 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
20420 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20430 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20440 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20450 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
20460 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
20470 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
20480 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
20490 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
204a0 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
204b0 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
204c0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
204d0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
204e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
204f0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
20500 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
20510 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
20520 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20530 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
20540 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
20550 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
20560 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
20570 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20580 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
20590 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
205a0 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
205b0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
205c0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
205d0 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
205e0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
205f0 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
20600 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
20610 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20620 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
20630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20640 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
20650 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
20660 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20670 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
20680 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
20690 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
206a0 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
206b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
206c0 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
206d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
206e0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
206f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20700 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20710 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
20720 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
20730 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20740 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20750 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20760 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
20770 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
20780 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20790 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
207a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
207b0 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
207c0 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
207d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
207e0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
207f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20800 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
20810 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
20820 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20830 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
20840 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20850 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
20860 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
20870 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
20880 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
20890 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
208a0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
208b0 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
208c0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
208d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
208e0 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
208f0 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c       33   /* NUL
20900 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
20910 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20920 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20930 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
20940 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
20950 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
20960 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  te3.**.** These 
20970 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
20980 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
20990 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
209a0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
209b0 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
209c0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
209d0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
209e0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
209f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20a00 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
20a10 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
20a20 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
20a30 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
20a40 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
20a50 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
20a60 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
20a70 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
20a80 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
20a90 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
20aa0 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
20ab0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
20ac0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
20ad0 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
20ae0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
20af0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
20b00 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
20b10 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
20b20 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
20b30 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
20b40 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
20b50 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
20b60 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
20b70 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
20b80 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
20b90 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
20ba0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
20bb0 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
20bc0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   The [SQLITE_TRA
20bd0 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
20be0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
20bf0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
20c00 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c  o limit.** the l
20c10 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20  ength of [bound 
20c20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e  parameter] expan
20c30 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70  sion in the outp
20c40 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72  ut of sqlite3_tr
20c50 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ace()..**.** ^Th
20c60 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
20c70 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
20c80 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
20c90 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
20ca0 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
20cb0 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
20cc0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
20cd0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
20ce0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
20cf0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
20d00 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
20d10 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
20d20 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
20d30 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
20d40 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
20d50 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
20d60 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
20d70 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
20d80 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
20d90 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
20da0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
20db0 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
20dc0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
20dd0 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
20de0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
20df0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
20e00 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
20e10 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
20e20 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20e30 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
20e40 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
20e50 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
20e60 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
20e70 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
20e80 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
20e90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
20ea0 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
20eb0 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
20ec0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
20ed0 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
20ee0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
20ef0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
20f00 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
20f10 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
20f20 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
20f30 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
20f40 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
20f50 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
20f60 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
20f70 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
20f80 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
20f90 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
20fa0 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
20fb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
20fc0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
20fd0 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
20fe0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
20ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
21000 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
21010 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
21020 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
21030 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
21040 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
21050 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
21060 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
21070 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
21080 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
21090 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
210a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
210b0 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
210c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
210d0 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
210e0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
210f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
21100 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
21110 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
21120 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
21130 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
21140 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
21150 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
21160 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
21170 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
21180 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
21190 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
211a0 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
211b0 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
211c0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
211d0 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
211e0 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
211f0 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
21200 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
21210 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
21220 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
21230 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
21240 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
21250 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
21260 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
21270 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
21280 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
21290 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
212a0 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
212b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
212c0 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
212d0 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
212e0 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
212f0 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
21300 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
21310 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
21320 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
21330 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
21340 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
21350 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
21360 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
21370 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
21380 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
21390 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
213a0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
213b0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
213c0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
213d0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
213e0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
213f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
21400 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
21410 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
21420 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
21430 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
21440 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
21450 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
21460 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
21470 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
21480 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
21490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
214a0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
214b0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
214c0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
214d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
214e0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
214f0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
21500 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
21510 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21520 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
21530 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
21540 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
21550 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
21560 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
21570 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
21580 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
21590 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
215a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
215b0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
215c0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
215d0 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
215e0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
215f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
21600 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
21610 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
21620 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
21630 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
21640 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
21650 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
21660 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21670 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
21680 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
21690 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
216a0 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
216b0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
216c0 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
216d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
216e0 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
216f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
21700 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
21710 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
21720 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
21730 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
21740 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
21750 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
21760 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
21770 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
21780 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
21790 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
217a0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
217b0 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
217c0 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
217d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
217e0 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
217f0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
21800 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
21810 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
21820 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
21830 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
21840 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
21850 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
21860 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
21870 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
21880 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
21890 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
218a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
218b0 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
218c0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
218d0 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
218e0 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
218f0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
21900 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
21910 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
21920 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
21930 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
21940 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
21950 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20  t encoding will 
21960 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74  be UTF-8 for dat
21970 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75  abases created u
21980 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  sing.** sqlite3_
21990 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
219a0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54  3_open_v2().  ^T
219b0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
219c0 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65  ing for database
219d0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69  s.** created usi
219e0 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  ng sqlite3_open1
219f0 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  6() will be UTF-
21a00 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
21a10 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
21a20 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
21a30 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
21a40 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
21a50 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
21a60 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
21a70 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
21a80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
21a90 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
21aa0 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
21ab0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
21ac0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
21ad0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
21ae0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
21af0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
21b00 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
21b10 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
21b20 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
21b30 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
21b40 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
21b50 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
21b60 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
21b70 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
21b80 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
21b90 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
21ba0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
21bb0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
21bc0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
21bd0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
21be0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
21bf0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
21c00 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
21c10 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
21c20 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
21c30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
21c40 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
21c50 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
21c60 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
21c70 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
21c80 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
21c90 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
21ca0 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
21cb0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
21cc0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
21cd0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
21ce0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
21cf0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
21d00 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
21d10 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
21d20 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
21d30 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
21d40 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
21d50 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
21d60 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
21d70 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
21d80 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
21d90 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
21da0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
21db0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
21dc0 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
21dd0 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
21de0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
21df0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
21e00 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
21e10 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
21e20 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
21e30 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
21e40 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
21e50 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
21e60 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
21e70 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
21e80 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
21e90 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
21ea0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
21eb0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21ec0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
21ed0 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
21ee0 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
21ef0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
21f00 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
21f10 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
21f20 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
21f30 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
21f40 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
21f50 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
21f60 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
21f70 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
21f80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
21f90 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
21fa0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
21fb0 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
21fc0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
21fd0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
21fe0 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
21ff0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
22000 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
22010 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
22020 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
22030 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
22040 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
22050 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
22060 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
22070 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
22080 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
22090 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
220a0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
220b0 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
220c0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
220d0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
220e0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
220f0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
22100 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
22110 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
22120 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
22130 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
22140 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
22150 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
22160 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
22170 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
22180 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
22190 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
221a0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
221b0 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
221c0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
221d0 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
221e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
221f0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
22200 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
22210 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
22220 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
22230 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
22240 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
22250 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
22260 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
22270 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
22280 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
22290 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
222a0 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
222b0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
222c0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
222d0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
222e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
222f0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
22300 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
22310 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
22320 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
22330 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
22340 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
22350 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
22360 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
22370 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
22380 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
22390 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
223a0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
223b0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
223c0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
223d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
223e0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
223f0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
22400 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
22410 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
22420 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
22430 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
22440 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
22450 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
22460 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
22470 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
22480 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
22490 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
224a0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
224b0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
224c0 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
224d0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
224e0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
224f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22500 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
22510 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
22520 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
22530 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
22540 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
22550 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
22560 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
22570 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
22580 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
22590 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
225a0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
225b0 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
225c0 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
225d0 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
225e0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
225f0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
22600 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
22610 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
22620 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
22630 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
22640 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
22650 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
22660 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
22670 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
22680 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
22690 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
226a0 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
226b0 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
226c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
226d0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
226e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
226f0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
22700 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
22710 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
22720 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
22730 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
22740 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
22750 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
22760 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
22770 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
22780 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
22790 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
227a0 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
227b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
227c0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
227d0 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
227e0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
227f0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
22800 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
22810 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
22820 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
22830 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
22840 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
22850 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
22860 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
22870 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
22880 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
22890 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
228a0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
228b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
228c0 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
228d0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
228e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
228f0 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
22900 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
22910 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
22920 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
22930 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
22940 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
22950 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
22960 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
22970 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
22980 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
22990 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
229a0 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
229b0 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
229c0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
229d0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
229e0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
229f0 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
22a00 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
22a10 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
22a20 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
22a30 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
22a40 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
22a50 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
22a60 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
22a70 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
22a80 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
22a90 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
22aa0 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
22ab0 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
22ac0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
22ad0 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
22ae0 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
22af0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
22b00 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
22b10 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
22b20 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
22b30 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
22b40 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
22b50 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
22b60 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
22b70 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
22b80 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
22b90 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
22ba0 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
22bb0 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
22bc0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
22bd0 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
22be0 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
22bf0 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
22c00 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
22c10 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
22c20 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
22c30 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
22c40 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
22c50 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
22c60 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
22c70 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
22c80 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73  .** ^(On windows
22c90 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
22ca0 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
22cb0 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
22cc0 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
22cd0 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
22ce0 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  ").)^.**.** [[co
22cf0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
22d00 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
22d10 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
22d20 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
22d30 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
22d40 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
22d50 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
22d60 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
22d70 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
22d80 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
22d90 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
22da0 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62  SQLite and its b
22db0 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20  uilt-in [VFSes] 
22dc0 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
22dd0 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79   following query
22de0 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
22df0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
22e00 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
22e10 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
22e20 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
22e30 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
22e40 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
22e50 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
22e60 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
22e70 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
22e80 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
22e90 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
22ea0 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
22eb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
22ec0 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
22ed0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
22ee0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
22ef0 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
22f00 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
22f10 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
22f20 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
22f30 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
22f40 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
22f50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
22f60 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
22f70 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
22f80 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
22f90 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
22fa0 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
22fb0 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
22fc0 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
22fd0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
22fe0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
22ff0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
23000 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
23010 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
23020 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
23030 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
23040 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
23050 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20  "ro", "rw",.**  
23060 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65     "rwc", or "me
23070 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e  mory". Attemptin
23080 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61  g to set it to a
23090 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69  ny other value i
230a0 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f  s.**     an erro
230b0 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
230c0 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
230d0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
230e0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
230f0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
23100 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
23110 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
23120 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
23130 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
23140 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
23150 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
23160 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
23170 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68  pen_v2(). ^If th
23180 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
23190 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20   set to .**     
231a0 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64  "rw", then the d
231b0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
231c0 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65  d for read-write
231d0 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65   (but not create
231e0 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  ) .**     access
231f0 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f  , as if SQLITE_O
23200 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62  PEN_READWRITE (b
23210 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50  ut not SQLITE_OP
23220 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a  EN_CREATE) had .
23230 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e  **     been set.
23240 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73   ^Value "rwc" is
23250 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
23260 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20  etting both .** 
23270 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
23280 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51  READWRITE and SQ
23290 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
232a0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  .  ^If the mode 
232b0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
232c0 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22   set to "memory"
232d0 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e   then a pure [in
232e0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
232f0 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61  ] that never rea
23300 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69  ds.**     or wri
23310 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73  tes from disk is
23320 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e   used. ^It is an
23330 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
23340 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a  y a value for.**
23350 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61       the mode pa
23360 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
23370 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
23380 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
23390 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74  fied by.**     t
233a0 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
233b0 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
233c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
233d0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
233e0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
233f0 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
23400 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
23410 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
23420 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
23430 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
23440 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
23450 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
23460 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
23470 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
23480 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
23490 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
234a0 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
234b0 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
234c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
234d0 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
234e0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
234f0 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
23500 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
23510 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
23520 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
23530 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
23540 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
23550 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
23560 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
23570 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
23580 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
23590 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
235a0 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
235b0 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
235c0 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79  ior requested by
235d0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
235e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
235f0 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
23600 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
23610 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20  CHE flag..**.** 
23620 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62   <li> <b>psow</b
23630 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72  >: ^The psow par
23640 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73  ameter indicates
23650 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
23660 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65  the.**     [powe
23670 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d  rsafe overwrite]
23680 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f   property does o
23690 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79  r does not apply
236a0 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73   to the.**     s
236b0 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20  torage media on 
236c0 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61  which the databa
236d0 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e  se file resides.
236e0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
236f0 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65  nolock</b>: ^The
23700 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65   nolock paramete
23710 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
23720 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a  uery parameter.*
23730 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73  *     which if s
23740 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65  et disables file
23750 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c   locking in roll
23760 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64  back journal mod
23770 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20  es.  This.**    
23780 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61   is useful for a
23790 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62  ccessing a datab
237a0 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73  ase on a filesys
237b0 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  tem that does no
237c0 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74  t.**     support
237d0 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69   locking.  Cauti
237e0 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f  on:  Database co
237f0 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72  rruption might r
23800 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20  esult if two.** 
23810 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63      or more proc
23820 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74  esses write to t
23830 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
23840 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20   and any one of 
23850 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f  those.**     pro
23860 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f  cesses uses nolo
23870 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ck=1..**.**  <li
23880 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f  > <b>immutable</
23890 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62  b>: ^The immutab
238a0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  le parameter is 
238b0 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a  a boolean query.
238c0 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
238d0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
238e0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
238f0 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64  e file is stored
23900 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d   on.**     read-
23910 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68  only media.  ^Wh
23920 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20  en immutable is 
23930 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75  set, SQLite assu
23940 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
23950 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c      database fil
23960 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  e cannot be chan
23970 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70  ged, even by a p
23980 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68  rocess with high
23990 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c  er.**     privil
239a0 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ege, and so the 
239b0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
239c0 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64  ed read-only and
239d0 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20   all locking.** 
239e0 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64      and change d
239f0 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61  etection is disa
23a00 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20  bled.  Caution: 
23a10 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75  Setting the immu
23a20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f  table.**     pro
23a30 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62  perty on a datab
23a40 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f  ase file that do
23a50 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67  es in fact chang
23a60 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20  e can result.** 
23a70 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74      in incorrect
23a80 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61   query results a
23a90 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  nd/or [SQLITE_CO
23aa0 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a  RRUPT] errors..*
23ab0 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20  *     See also: 
23ac0 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
23ad0 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20  MUTABLE]..**    
23ae0 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a     .** </ul>.**.
23af0 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
23b00 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
23b10 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
23b20 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
23b30 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
23b40 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
23b50 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
23b60 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
23b70 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
23b80 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
23b90 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
23ba0 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
23bb0 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
23bc0 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
23bd0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
23be0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
23bf0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
23c00 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
23c10 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
23c20 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
23c30 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
23c40 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
23c50 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
23c60 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
23c70 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
23c80 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
23c90 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
23ca0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
23cb0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
23cc0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
23cd0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
23ce0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
23cf0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
23d00 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
23d10 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
23d20 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23d30 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
23d40 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
23d50 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
23d60 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
23d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
23d80 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
23d90 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
23da0 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
23db0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
23dc0 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
23dd0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
23de0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
23df0 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
23e00 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
23e10 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
23e20 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
23e30 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
23e40 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
23e50 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
23e60 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
23e70 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
23e80 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
23e90 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
23ea0 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
23eb0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
23ec0 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
23ed0 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
23ee0 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
23ef0 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
23f00 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
23f10 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
23f20 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
23f30 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
23f40 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
23f50 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
23f60 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
23f70 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
23f80 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
23f90 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
23fa0 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
23fb0 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
23fc0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
23fd0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
23fe0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
23ff0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
24000 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
24010 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
24020 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
24030 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
24040 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
24050 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
24060 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
24070 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
24080 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
24090 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
240a0 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c  s=unix-dotfile <
240b0 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
240c0 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
240d0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
240e0 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
240f0 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c  VFS "unix-dotfil
24100 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  e".**          t
24110 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c  hat uses dot-fil
24120 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70  es in place of p
24130 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f  osix advisory lo
24140 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cking..** <tr><t
24150 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
24160 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
24170 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
24180 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
24190 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
241a0 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
241b0 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
241c0 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
241d0 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
241e0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
241f0 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
24200 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
24210 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
24220 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
24230 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
24240 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
24250 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
24260 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
24270 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
24280 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
24290 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
242a0 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
242b0 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
242c0 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
242d0 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
242e0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
242f0 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
24300 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
24310 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
24320 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
24330 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
24340 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
24350 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
24360 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
24370 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
24380 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
24390 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
243a0 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
243b0 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
243c0 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
243d0 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
243e0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
243f0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
24400 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
24410 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
24420 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
24430 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
24440 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
24450 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
24460 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
24470 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
24480 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
24490 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
244a0 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
244b0 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
244c0 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
244d0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
244e0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
244f0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
24500 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
24510 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
24520 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
24530 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
24540 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
24550 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
24560 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
24570 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
24580 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
24590 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
245a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
245b0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
245c0 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
245d0 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
245e0 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
245f0 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
24600 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
24610 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
24620 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
24630 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
24640 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24650 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
24660 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
24670 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
24680 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
24690 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
246a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
246b0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
246c0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
246d0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
246e0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
246f0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
24700 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
24710 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
24720 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
24730 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
24740 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
24750 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
24760 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
24770 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
24780 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
24790 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
247a0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
247b0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
247c0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
247d0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
247e0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
247f0 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
24800 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
24810 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
24820 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
24830 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
24840 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
24850 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
24860 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
24870 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
24880 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
24890 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
248a0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
248b0 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
248c0 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
248d0 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
248e0 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
248f0 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
24900 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
24910 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
24920 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
24930 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24940 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
24950 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
24960 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
24970 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
24980 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
24990 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
249a0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
249b0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
249c0 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
249d0 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
249e0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
249f0 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
24a00 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
24a10 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
24a20 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
24a30 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
24a40 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
24a50 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24a60 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24a70 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
24a80 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
24a90 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
24aa0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
24ab0 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
24ac0 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
24ad0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24ae0 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
24af0 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
24b00 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
24b10 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
24b20 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
24b30 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
24b40 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
24b50 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
24b60 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
24b70 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
24b80 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
24b90 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
24ba0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
24bb0 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
24bc0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
24bd0 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
24be0 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
24bf0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
24c00 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
24c10 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24c20 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
24c30 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
24c40 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
24c50 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
24c60 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
24c70 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
24c80 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
24c90 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
24ca0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
24cb0 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
24cc0 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
24cd0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
24ce0 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
24cf0 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
24d00 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
24d10 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24d20 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
24d30 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
24d40 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
24d50 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
24d60 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
24d70 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
24d80 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
24d90 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
24da0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
24db0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
24dc0 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
24dd0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
24de0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
24df0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
24e00 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
24e10 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
24e20 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
24e30 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
24e40 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
24e50 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
24e60 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
24e70 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
24e80 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
24e90 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
24ea0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
24eb0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
24ec0 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
24ed0 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
24ee0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
24ef0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
24f00 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
24f10 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
24f20 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
24f30 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
24f40 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
24f50 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
24f60 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
24f70 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
24f80 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
24f90 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
24fa0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24fb0 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
24fc0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
24fd0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
24fe0 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
24ff0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
25000 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
25010 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
25020 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
25030 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
25040 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
25050 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
25060 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
25070 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
25080 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
25090 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  int sqlite3_uri_
250a0 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
250b0 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
250c0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
250d0 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71  nt bDefault);.sq
250e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
250f0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
25100 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
25110 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
25120 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
25130 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
25140 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
25150 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
25160 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lite3.**.** ^If 
25170 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
25180 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
25190 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ll associated wi
251a0 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  th .** [database
251b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66   connection] D f
251c0 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ailed, then the 
251d0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
251e0 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  D) interface.** 
251f0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
25200 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
25210 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72  ] or [extended r
25220 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
25230 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c  that.** API call
25240 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74  ..** If the most
25250 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
25260 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c   was successful,
25270 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
25280 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
25290 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
252a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
252b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
252c0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
252d0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
252e0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
252f0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
25300 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
25310 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
25320 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
25330 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
25340 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
25350 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
25360 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
25370 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
25380 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
25390 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
253a0 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
253b0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
253c0 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
253d0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
253e0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
253f0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
25400 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
25410 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
25420 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
25430 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
25440 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
25450 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
25460 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
25470 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
25480 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
25490 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
254a0 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
254b0 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
254c0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
254d0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
254e0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
254f0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
25500 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
25510 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25520 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
25530 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
25540 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
25550 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
25560 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
25570 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
25580 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
25590 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
255a0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
255b0 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
255c0 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
255d0 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
255e0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
255f0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
25600 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
25610 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
25620 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
25630 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
25640 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
25650 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
25660 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
25670 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
25680 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
25690 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
256a0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
256b0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
256c0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
256d0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
256e0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
256f0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
25700 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
25710 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
25720 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
25730 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
25740 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
25750 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
25760 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25770 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
25780 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
25790 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
257a0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
257b0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
257c0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
257d0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
257e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
257f0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
25800 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
25810 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
25820 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
25830 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
25840 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
25850 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
25860 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
25870 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
25880 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
25890 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
258a0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
258b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
258c0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
258d0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
258e0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
258f0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
25900 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
25910 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
25920 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
25930 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
25940 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
25950 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
25960 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
25970 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
25980 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
25990 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
259a0 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  *);.const char *
259b0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
259c0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
259d0 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53  3REF: Prepared S
259e0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
259f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
25a00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25a10 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
25a20 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
25a30 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
25a40 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
25a50 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
25a60 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a   statement that.
25a70 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70  ** has been comp
25a80 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79  iled into binary
25a90 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61   form and is rea
25aa0 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  dy to be evaluat
25ab0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20  ed..**.** Think 
25ac0 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  of each SQL stat
25ad0 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72  ement as a separ
25ae0 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f  ate computer pro
25af0 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72  gram.  The.** or
25b00 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20  iginal SQL text 
25b10 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
25b20 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74   A prepared stat
25b30 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a  ement object .**
25b40 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64   is the compiled
25b50 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41   object code.  A
25b60 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63  ll SQL must be c
25b70 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a  onverted into a.
25b80 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
25b90 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20  ement before it 
25ba0 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a  can be run..**.*
25bb0 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65  * The life-cycle
25bc0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73   of a prepared s
25bd0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
25be0 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b  usually goes lik
25bf0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
25c00 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
25c10 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  e the prepared s
25c20 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
25c30 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
25c40 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a  repare_v2()]..**
25c50 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
25c60 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73  s to [parameters
25c70 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
25c80 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
25c90 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
25ca0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
25cb0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
25cc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25cd0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
25ce0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
25cf0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
25d00 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
25d10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
25d20 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
25d30 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
25d40 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
25d50 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
25d60 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
25d70 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
25d80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25d90 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  ()]..** </ol>.*/
25da0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
25db0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
25dc0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
25dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
25de0 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d  time Limits.** M
25df0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
25e00 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
25e10 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
25e20 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
25e30 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
25e40 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
25e50 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
25e60 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
25e70 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
25e80 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
25e90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
25ea0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
25eb0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
25ec0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
25ed0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
25ee0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
25ef0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
25f00 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
25f10 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
25f20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
25f30 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
25f40 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
25f50 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
25f60 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
25f70 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
25f80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
25f90 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
25fa0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
25fb0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
25fc0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
25fd0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
25fe0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
25ff0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
26000 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
26010 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
26020 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
26030 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
26040 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
26050 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
26060 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
26070 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
26080 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
26090 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
260a0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
260b0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
260c0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
260d0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
260e0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
260f0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
26100 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
26110 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
26120 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
26130 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
26140 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
26150 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
26160 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
26170 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
26180 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26190 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
261a0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
261b0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
261c0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
261d0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
261e0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
261f0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
26200 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
26210 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
26220 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
26230 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
26240 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
26250 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
26260 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
26270 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
26280 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
26290 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
262a0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
262b0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
262c0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
262d0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
262e0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
262f0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
26300 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
26310 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
26320 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
26330 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
26340 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
26350 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
26360 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
26370 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
26380 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
26390 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
263a0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
263b0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
263c0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
263d0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
263e0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
263f0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
26400 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
26410 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
26420 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
26430 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
26440 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
26450 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
26460 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
26470 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
26480 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
26490 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
264a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
264b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
264c0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
264d0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
264e0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
264f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
26500 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
26510 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
26520 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
26530 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
26540 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
26550 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
26560 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
26570 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
26580 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
26590 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
265a0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
265b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
265c0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
265d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
265e0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
265f0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
26600 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
26610 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
26620 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
26630 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
26640 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
26650 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
26660 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
26670 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
26680 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
26690 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
266a0 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
266b0 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
266c0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
266d0 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
266e0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
266f0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
26700 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
26710 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
26720 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
26730 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
26740 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
26750 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26760 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
26770 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26780 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
26790 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
267a0 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
267b0 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
267c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
267d0 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
267e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
267f0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
26800 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26810 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
26820 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
26830 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
26840 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26850 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
26860 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26870 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
26880 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26890 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
268a0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
268b0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
268c0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
268d0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
268e0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
268f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
26900 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
26910 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
26920 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
26930 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
26940 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26950 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
26960 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26970 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
26980 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26990 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
269a0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
269b0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
269c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
269d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
269e0 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
269f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26a00 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
26a10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26a20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26a30 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
26a40 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
26a50 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
26a60 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26a70 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
26a80 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26a90 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
26aa0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26ab0 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
26ac0 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
26ad0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
26ae0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
26af0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
26b00 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
26b10 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
26b20 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
26b30 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
26b40 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
26b50 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
26b60 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
26b70 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
26b80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26b90 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
26ba0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26bb0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
26bc0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26bd0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
26be0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
26bf0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
26c00 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
26c10 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
26c20 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26c30 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
26c40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26c50 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26c60 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
26c70 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
26c80 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
26c90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
26ca0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
26cb0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
26cc0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
26cd0 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
26ce0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26cf0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
26d00 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
26d10 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
26d20 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
26d30 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
26d40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26d50 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
26d60 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
26d70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
26d80 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
26d90 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26da0 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
26db0 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
26dc0 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
26dd0 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
26de0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26df0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
26e00 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26e10 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
26e20 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
26e30 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
26e40 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
26e50 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
26e60 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26e70 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
26e80 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
26e90 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
26ea0 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
26eb0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26ec0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
26ed0 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
26ee0 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
26ef0 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
26f00 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
26f10 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
26f20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
26f30 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
26f40 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
26f50 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
26f60 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
26f70 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
26f80 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
26f90 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26fa0 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
26fb0 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
26fc0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26fd0 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
26fe0 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
26ff0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27000 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
27010 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
27020 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27030 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
27040 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
27050 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27060 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
27070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
27080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27090 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
270a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
270b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
270c0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
270d0 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
270e0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
270f0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
27100 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
27110 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
27120 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
27130 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
27140 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
27150 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
27160 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
27170 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
27180 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
27190 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
271a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
271b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
271c0 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
271d0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
271e0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
271f0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
27200 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
27210 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
27220 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
27230 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
27240 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
27250 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
27260 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
27270 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
27280 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
27290 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
272a0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
272b0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
272c0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
272d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
272e0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
272f0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
27300 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
27310 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
27320 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
27330 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
27340 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
27350 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
27360 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
27370 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
27380 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
27390 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
273a0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
273b0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
273c0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
273d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
273e0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
273f0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
27400 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
27410 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
27420 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
27430 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
27440 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
27450 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
27460 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
27470 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
27480 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
27490 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
274a0 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
274b0 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
274c0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
274d0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
274e0 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
274f0 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
27500 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
27510 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
27520 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
27530 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
27540 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
27550 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
27560 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
27570 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
27580 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
27590 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
275a0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
275b0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
275c0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
275d0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
275e0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
275f0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
27600 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
27610 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
27620 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
27630 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
27640 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
27650 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
27660 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
27670 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
27680 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
27690 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
276a0 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
276b0 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
276c0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
276d0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
276e0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
276f0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
27700 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
27710 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
27720 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
27730 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
27740 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
27750 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
27760 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27770 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
27780 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
27790 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
277a0 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
277b0 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
277c0 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
277d0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
277e0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
277f0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
27800 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
27810 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
27820 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
27830 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
27840 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
27850 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
27860 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
27870 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
27880 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
27890 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
278a0 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
278b0 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
278c0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
278d0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
278e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
278f0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
27900 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
27910 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
27920 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
27930 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
27940 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27950 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
27960 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
27970 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
27980 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
27990 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
279a0 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
279b0 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
279c0 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
279d0 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
279e0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
279f0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
27a00 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
27a10 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
27a20 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
27a30 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
27a40 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
27a50 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
27a60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
27a70 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
27a80 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
27a90 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
27aa0 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
27ab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
27ac0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
27ad0 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
27ae0 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
27af0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
27b00 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
27b10 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
27b20 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
27b30 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
27b40 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
27b50 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
27b60 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
27b70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
27b80 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
27b90 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
27ba0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
27bb0 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
27bc0 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
27bd0 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
27be0 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
27bf0 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
27c00 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
27c10 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
27c20 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
27c30 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
27c40 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
27c50 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
27c60 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
27c70 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
27c80 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
27c90 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
27ca0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
27cb0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
27cc0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
27cd0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
27ce0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
27cf0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
27d00 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
27d10 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
27d20 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
27d30 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
27d40 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
27d50 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
27d60 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
27d70 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
27d80 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
27d90 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
27da0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
27db0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
27dc0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
27dd0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
27de0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
27df0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
27e00 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
27e10 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
27e20 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
27e30 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
27e40 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
27e50 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
27e60 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
27e70 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
27e80 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
27e90 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
27ea0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
27eb0 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
27ec0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
27ed0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
27ee0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
27ef0 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
27f00 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
27f10 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
27f20 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
27f30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
27f40 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
27f50 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
27f60 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
27f70 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
27f80 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
27f90 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
27fa0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
27fb0 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
27fc0 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
27fd0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
27fe0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
27ff0 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
28000 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
28010 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
28020 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
28030 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
28040 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
28050 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
28060 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
28070 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
28080 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
28090 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
280a0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
280b0 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
280c0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
280d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
280e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
280f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
28100 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
28110 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
28120 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
28130 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
28140 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
28150 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
28160 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
28170 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
28180 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
28190 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
281a0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
281b0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
281c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
281d0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
281e0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
281f0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28200 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
28210 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
28220 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
28230 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
28240 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
28250 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
28260 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
28270 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
28280 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
28290 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
282a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
282b0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
282c0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
282d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
282e0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
282f0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
28300 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28310 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
28320 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
28330 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
28340 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
28350 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
28360 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
28370 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
28380 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
28390 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
283a0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
283b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
283c0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
283d0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
283e0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
283f0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
28400 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
28410 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
28420 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
28430 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
28440 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
28450 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
28460 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
28470 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
28480 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
28490 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
284a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
284b0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
284c0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
284d0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
284e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
284f0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
28500 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
28510 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
28520 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
28530 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
28540 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28550 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
28560 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
28570 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
28580 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
28590 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
285a0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
285b0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
285c0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
285d0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
285e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
285f0 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
28600 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20  tatement SQL.** 
28610 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
28620 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
28630 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
28640 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
28650 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
28660 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
28670 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
28680 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
28690 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
286a0 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
286b0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
286c0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
286d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
286e0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
286f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
28700 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
28710 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
28720 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
28730 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
28740 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
28750 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
28760 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
28770 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
28780 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
28790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
287a0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
287b0 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
287c0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
287d0 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
287e0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
287f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28800 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
28810 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
28820 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
28830 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
28840 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
28850 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
28860 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28870 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
28880 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
28890 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
288a0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
288b0 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
288c0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
288d0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
288e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
288f0 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
28900 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
28910 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
28920 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
28930 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
28940 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
28950 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
28960 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
28970 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
28980 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
28990 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
289a0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
289b0 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
289c0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
289d0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
289e0 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
289f0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
28a00 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
28a10 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
28a20 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
28a30 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
28a40 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
28a50 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
28a60 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
28a70 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
28a80 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
28a90 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
28aa0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
28ab0 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
28ac0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
28ad0 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
28ae0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
28af0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
28b00 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
28b10 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
28b20 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
28b30 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
28b40 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
28b50 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
28b60 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
28b70 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
28b80 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
28b90 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
28ba0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
28bb0 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
28bc0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
28bd0 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
28be0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
28bf0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
28c00 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
28c10 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
28c20 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
28c30 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
28c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
28c50 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
28c60 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
28c70 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
28c80 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
28c90 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69  es on disk..*/.i
28ca0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
28cb0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
28cc0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
28cd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28ce0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
28cf0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
28d00 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
28d10 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
28d20 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
28d30 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
28d40 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
28d50 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
28d60 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
28d70 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
28d80 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
28d90 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
28da0 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
28db0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
28dc0 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
28dd0 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f  either run to co
28de0 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e  mpletion (return
28df0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ed.** [SQLITE_DO
28e00 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  NE] from [sqlite
28e10 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a  3_step(S)]) nor.
28e20 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
28e30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
28e40 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
28e50 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
28e60 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
28e70 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
28e80 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
28e90 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
28ea0 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
28eb0 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
28ec0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
28ed0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
28ee0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
28ef0 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
28f00 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
28f10 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
28f20 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
28f30 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
28f40 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
28f50 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
28f60 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
28f70 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
28f80 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
28f90 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
28fa0 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
28fb0 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
28fc0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
28fd0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
28fe0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
28ff0 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
29000 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
29010 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
29020 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
29030 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
29040 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
29050 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
29060 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
29070 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
29080 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
29090 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
290a0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
290b0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
290c0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
290d0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
290e0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
290f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29100 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
29110 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
29120 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29130 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
29140 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
29150 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
29160 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
29170 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
29180 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
29190 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
291a0 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
291b0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
291c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
291d0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
291e0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
291f0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
29200 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
29210 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
29220 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
29230 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
29240 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
29250 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
29260 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
29270 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
29280 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29290 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
292a0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
292b0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
292c0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
292d0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
292e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
292f0 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
29300 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
29310 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
29320 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
29330 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
29340 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
29350 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29360 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a  3_value.  The.**
29370 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
29380 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  dup()] interface
29390 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
293a0 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20  construct a new 
293b0 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71  .** protected sq
293c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d  lite3_value from
293d0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
293e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
293f0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
29400 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
29410 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
29420 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
29430 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
29440 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
29450 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
29460 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
29470 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
29480 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
29490 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
294a0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
294b0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
294c0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
294d0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
294e0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
294f0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
29500 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
29510 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
29520 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
29530 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
29540 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
29550 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
29560 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
29570 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
29580 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
29590 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
295a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
295b0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
295c0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
295d0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
295e0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
295f0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
29600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29610 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
29620 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
29630 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
29640 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
29650 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
29660 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
29670 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
29680 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
29690 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
296a0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
296b0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
296c0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
296d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
296e0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
296f0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
29700 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
29710 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29720 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
29730 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
29740 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
29750 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
29760 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
29770 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
29780 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
29790 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
297a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
297b0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
297c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
297d0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
297e0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
297f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29800 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
29810 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
29820 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
29830 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
29840 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
29850 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
29860 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
29870 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
29880 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
29890 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
298a0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
298b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
298c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
298d0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
298e0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
298f0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
29900 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
29910 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
29920 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
29930 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
29940 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
29950 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
29960 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
29970 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
29980 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
29990 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
299a0 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
299b0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
299c0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
299d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
299e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
299f0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
29a00 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
29a10 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
29a20 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
29a30 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
29a40 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
29a50 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
29a60 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
29a70 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
29a80 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
29a90 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
29aa0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
29ab0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
29ac0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
29ad0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
29ae0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
29af0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
29b00 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
29b10 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
29b20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
29b30 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
29b40 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
29b50 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
29b60 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
29b70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
29b80 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
29b90 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
29ba0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
29bb0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
29bc0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
29bd0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
29be0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
29bf0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
29c00 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f  inding}.** METHO
29c10 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
29c20 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
29c30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
29c40 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
29c50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
29c60 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
29c70 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
29c80 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
29c90 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
29ca0 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
29cb0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
29cc0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
29cd0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
29ce0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
29cf0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
29d00 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
29d10 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
29d20 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
29d30 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
29d40 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
29d50 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
29d60 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
29d70 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
29d80 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
29d90 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
29da0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
29db0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
29dc0 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
29dd0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
29de0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
29df0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
29e00 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
29e10 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
29e20 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
29e30 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
29e40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
29e50 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
29e60 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
29e70 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
29e80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
29e90 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
29ea0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
29eb0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
29ec0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
29ed0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
29ee0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
29ef0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
29f00 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
29f10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
29f20 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
29f30 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
29f40 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
29f50 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
29f60 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
29f70 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
29f80 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
29f90 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
29fa0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
29fb0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
29fc0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
29fd0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
29fe0 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
29ff0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
2a000 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
2a010 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
2a020 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
2a030 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a040 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
2a050 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
2a060 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
2a070 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
2a080 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2a090 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
2a0a0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
2a0b0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
2a0c0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
2a0d0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
2a0e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
2a0f0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
2a100 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
2a110 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
2a120 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
2a130 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
2a140 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
2a150 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
2a160 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2a170 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2a180 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2a190 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2a1a0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2a1b0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
2a1c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
2a1d0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
2a1e0 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
2a1f0 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
2a200 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
2a210 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
2a220 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
2a230 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
2a240 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
2a250 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
2a260 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
2a270 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2a280 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
2a290 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
2a2a0 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
2a2b0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2a2c0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
2a2d0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
2a2e0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2a2f0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
2a300 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
2a310 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2a320 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a330 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2a340 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
2a350 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2a360 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
2a370 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
2a380 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2a390 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
2a3a0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2a3b0 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
2a3c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2a3d0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a3e0 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
2a3f0 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
2a400 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2a410 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
2a420 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
2a430 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2a440 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
2a450 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
2a460 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2a470 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73  nd_text16() or s
2a480 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a490 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61  64() then.** tha
2a4a0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2a4b0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
2a4c0 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
2a4d0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
2a4e0 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
2a4f0 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
2a500 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
2a510 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
2a520 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
2a530 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
2a540 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
2a550 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
2a560 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2a570 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
2a580 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
2a590 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
2a5a0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
2a5b0 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
2a5c0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
2a5d0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
2a5e0 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
2a5f0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
2a600 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2a610 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
2a620 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73  o the BLOB and s
2a630 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e  tring binding in
2a640 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61  terfaces.** is a
2a650 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
2a660 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2a670 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
2a680 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
2a690 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
2a6a0 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
2a6b0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2a6c0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
2a6d0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
2a6e0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
2a6f0 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20  he call to bind 
2a700 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49  API fails..** ^I
2a710 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2a720 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
2a730 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
2a740 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
2a750 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
2a760 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
2a770 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
2a780 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
2a790 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
2a7a0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2a7b0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
2a7c0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2a7d0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
2a7e0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2a7f0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
2a800 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
2a810 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
2a820 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
2a830 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
2a840 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2a850 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
2a860 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
2a870 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2a880 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a890 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65  text64() must be
2a8a0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49   one of.** [SQLI
2a8b0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
2a8c0 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54  E_UTF16], [SQLIT
2a8d0 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b  E_UTF16BE], or [
2a8e0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a  SQLITE_UTF16LE].
2a8f0 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ** to specify th
2a900 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68  e encoding of th
2a910 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68  e text in the th
2a920 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ird parameter.  
2a930 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20  If.** the sixth 
2a940 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2a950 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2a960 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
2a970 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76  the.** allowed v
2a980 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76  alues shown abov
2a990 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78  e, or if the tex
2a9a0 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  t encoding is di
2a9b0 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20  fferent.** from 
2a9c0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
2a9d0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69  cified by the si
2a9e0 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74  xth parameter, t
2a9f0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2aa00 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
2aa10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2aa20 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2aa30 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
2aa40 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
2aa50 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
2aa60 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
2aa70 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
2aa80 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
2aa90 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
2aaa0 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
2aab0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
2aac0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
2aad0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
2aae0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
2aaf0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
2ab00 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
2ab10 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
2ab20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
2ab30 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
2ab40 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
2ab50 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
2ab60 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
2ab70 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
2ab80 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
2ab90 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
2aba0 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
2abb0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2abc0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
2abd0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
2abe0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2abf0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
2ac00 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
2ac10 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
2ac20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ac30 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
2ac40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ac50 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
2ac60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2ac70 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
2ac80 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
2ac90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2aca0 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
2acb0 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
2acc0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2acd0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
2ace0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
2acf0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
2ad00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ad10 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
2ad20 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
2ad30 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
2ad40 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2ad50 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
2ad60 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
2ad70 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
2ad80 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
2ad90 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
2ada0 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
2adb0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
2adc0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
2add0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ade0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
2adf0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2ae00 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
2ae10 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
2ae20 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
2ae30 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
2ae40 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f  .** ^[SQLITE_TOO
2ae50 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65  BIG] might be re
2ae60 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69  turned if the si
2ae70 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f  ze of a string o
2ae80 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64  r BLOB.** exceed
2ae90 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64  s limits imposed
2aea0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
2aeb0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
2aec0 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a  T_LENGTH]) or.**
2aed0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
2aee0 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  GTH]..** ^[SQLIT
2aef0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
2af00 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
2af10 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
2af20 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
2af30 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
2af40 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2af50 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
2af60 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2af70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2af80 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2af90 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2afa0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2afb0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
2afc0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2afd0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2afe0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2aff0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2b000 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2b010 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
2b020 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2b030 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2b040 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2b050 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2b060 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
2b070 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2b080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2b090 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2b0a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b0b0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2b0c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
2b0d0 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
2b0e0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
2b0f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2b100 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
2b110 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
2b120 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2b130 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
2b140 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b150 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
2b160 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
2b170 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2b180 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b190 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e  t,const char*,in
2b1a0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2b1b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b1c0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
2b1d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2b1e0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2b1f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2b200 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2b210 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  nd_text64(sqlite
2b220 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b230 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
2b240 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2b250 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b260 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2b270 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
2b280 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74  r encoding);.int
2b290 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
2b2a0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2b2b0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
2b2c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2b2d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b2e0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
2b2f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2b300 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33   n);.int sqlite3
2b310 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34  _bind_zeroblob64
2b320 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b330 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  int, sqlite3_uin
2b340 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
2b350 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2b360 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
2b370 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2b380 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2b390 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
2b3a0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
2b3b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
2b3c0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
2b3d0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
2b3e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
2b3f0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
2b400 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
2b410 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
2b420 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
2b430 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
2b440 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
2b450 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2b460 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
2b470 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2b480 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
2b490 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
2b4a0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
2b4b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
2b4c0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
2b4d0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
2b4e0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
2b4f0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
2b500 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
2b510 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
2b520 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
2b530 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
2b540 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
2b550 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
2b560 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
2b570 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
2b580 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
2b590 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
2b5a0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
2b5b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2b5c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2b5d0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2b5e0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2b5f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2b600 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
2b610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b620 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2b630 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b640 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2b650 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2b660 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2b670 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
2b680 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
2b690 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2b6a0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2b6b0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2b6c0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
2b6d0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
2b6e0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
2b6f0 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
2b700 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
2b710 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2b720 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2b730 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
2b740 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
2b750 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2b760 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2b770 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
2b780 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
2b790 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
2b7a0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2b7b0 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
2b7c0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
2b7d0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
2b7e0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
2b7f0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
2b800 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
2b810 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
2b820 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
2b830 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2b840 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
2b850 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
2b860 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
2b870 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
2b880 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
2b890 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
2b8a0 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
2b8b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2b8c0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
2b8d0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
2b8e0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
2b8f0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
2b900 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
2b910 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
2b920 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
2b930 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
2b940 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
2b950 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2b960 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
2b970 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
2b980 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
2b990 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2b9a0 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
2b9b0 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
2b9c0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
2b9d0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2b9e0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
2b9f0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2ba00 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2ba10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2ba20 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2ba30 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2ba40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2ba50 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2ba60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ba70 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2ba80 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2ba90 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
2baa0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
2bab0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2bac0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bad0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
2bae0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
2baf0 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54  iven Name.** MET
2bb00 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2bb10 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2bb20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
2bb30 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
2bb40 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
2bb50 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
2bb60 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
2bb70 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
2bb80 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
2bb90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2bba0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2bbb0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2bbc0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
2bbd0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
2bbe0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
2bbf0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
2bc00 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2bc10 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
2bc20 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
2bc30 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
2bc40 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
2bc50 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
2bc60 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
2bc70 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
2bc80 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2bc90 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2bca0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2bcb0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2bcc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2bcd0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2bce0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2bcf0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2bd00 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a  ter_name()]..*/.
2bd10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2bd20 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2bd30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2bd40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2bd50 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2bd60 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2bd70 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2bd80 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2bd90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2bda0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43  e3_stmt.**.** ^C
2bdb0 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
2bdc0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
2bdd0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
2bde0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
2bdf0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
2be00 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2be10 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
2be20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2be30 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
2be40 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
2be50 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
2be60 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
2be70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
2be80 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
2be90 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2bea0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2beb0 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
2bec0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2bed0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2bee0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2bef0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2bf00 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2bf10 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2bf20 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2bf30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bf40 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2bf50 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2bf60 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2bf70 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2bf80 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2bf90 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2bfa0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2bfb0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2bfc0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2bfd0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
2bfe0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2bff0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2c000 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2c010 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2c020 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2c030 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2c040 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c050 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2c060 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2c070 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
2c080 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
2c090 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
2c0a0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2c0b0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2c0c0 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
2c0d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2c0e0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
2c0f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2c100 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2c110 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
2c120 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
2c130 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2c140 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
2c150 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2c160 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
2c170 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2c180 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2c190 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
2c1a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2c1b0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2c1c0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2c1d0 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
2c1e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2c1f0 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
2c200 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
2c210 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
2c220 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
2c230 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2c240 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
2c250 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
2c260 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
2c270 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2c280 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
2c290 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c2a0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2c2b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2c2c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2c2d0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2c2e0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2c2f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c300 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2c310 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2c320 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
2c330 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2c340 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
2c350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2c360 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
2c370 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
2c380 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
2c390 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
2c3a0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
2c3b0 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
2c3c0 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
2c3d0 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
2c3e0 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
2c3f0 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
2c400 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
2c410 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2c420 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2c430 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
2c440 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
2c450 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
2c460 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
2c470 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
2c480 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
2c490 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
2c4a0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
2c4b0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
2c4c0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
2c4d0 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
2c4e0 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
2c4f0 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
2c500 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
2c510 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ext..*/.const ch
2c520 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2c530 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
2c540 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
2c550 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2c560 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2c570 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c580 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
2c590 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
2c5a0 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
2c5b0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
2c5c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2c5d0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2c5e0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2c5f0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2c600 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2c610 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2c620 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2c630 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2c640 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2c650 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2c660 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2c670 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2c680 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2c690 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2c6a0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2c6b0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2c6c0 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2c6d0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2c6e0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2c6f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c700 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2c710 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2c720 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2c730 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2c740 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2c750 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2c760 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2c770 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2c780 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2c790 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2c7a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2c7b0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2c7c0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2c7d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c7e0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2c7f0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2c800 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2c810 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2c820 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2c830 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2c840 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2c850 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2c860 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2c870 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2c880 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2c890 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2c8a0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2c8b0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2c8c0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2c8d0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2c8e0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2c8f0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2c900 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2c910 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2c920 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2c930 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2c940 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2c950 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2c960 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2c970 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2c980 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2c990 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2c9a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2c9b0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2c9c0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2c9d0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2c9e0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2c9f0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2ca00 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2ca10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2ca20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2ca30 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2ca40 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2ca50 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2ca60 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2ca70 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2ca80 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2ca90 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2caa0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2cab0 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2cac0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2cad0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2cae0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2caf0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2cb00 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2cb10 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2cb20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2cb30 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2cb40 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2cb50 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2cb60 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2cb70 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2cb80 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2cb90 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2cba0 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2cbb0 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2cbc0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2cbd0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2cbe0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2cbf0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2cc00 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2cc10 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2cc20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2cc30 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2cc40 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2cc50 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2cc60 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2cc70 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2cc80 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2cc90 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2cca0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2ccb0 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2ccc0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2ccd0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2cce0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ccf0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2cd00 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2cd10 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2cd20 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2cd30 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2cd40 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2cd50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2cd60 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2cd70 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2cd80 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2cd90 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2cda0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2cdb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cdc0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2cdd0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2cde0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2cdf0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2ce00 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2ce10 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2ce20 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2ce30 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2ce40 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2ce50 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2ce60 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2ce70 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2ce80 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2ce90 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2cea0 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2ceb0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2cec0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2ced0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2cee0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2cef0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2cf00 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2cf10 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2cf20 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2cf30 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2cf40 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2cf50 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2cf60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2cf70 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2cf80 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2cf90 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2cfa0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2cfb0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2cfc0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
2cfd0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2cfe0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2cff0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2d000 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
2d010 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2d020 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
2d030 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
2d040 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
2d050 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
2d060 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
2d070 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
2d080 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2d090 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
2d0a0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2d0b0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
2d0c0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
2d0d0 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
2d0e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2d0f0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
2d100 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
2d110 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
2d120 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
2d130 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2d140 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2d150 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
2d160 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
2d170 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2d180 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
2d190 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2d1a0 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
2d1b0 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
2d1c0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
2d1d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
2d1e0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2d1f0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
2d200 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
2d210 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
2d220 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
2d230 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
2d240 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
2d250 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
2d260 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
2d270 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
2d280 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
2d290 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
2d2a0 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
2d2b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2d2c0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
2d2d0 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
2d2e0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
2d2f0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
2d300 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
2d310 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
2d320 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
2d330 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
2d340 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
2d350 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
2d360 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
2d370 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
2d380 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
2d390 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
2d3a0 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
2d3b0 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
2d3c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2d3d0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
2d3e0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
2d3f0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
2d400 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
2d410 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73   values..*/.cons
2d420 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2d430 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
2d440 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d450 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2d460 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2d470 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
2d480 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2d490 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
2d4a0 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
2d4b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48  tatement.** METH
2d4c0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2d4d0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2d4e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d4f0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2d500 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2d510 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2d520 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2d530 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d540 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2d550 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2d560 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2d570 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2d580 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2d590 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2d5a0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2d5b0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2d5c0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2d5d0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2d5e0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2d5f0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2d600 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2d610 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2d620 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2d630 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2d640 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2d650 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2d660 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2d670 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2d680 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2d690 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2d6a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2d6b0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2d6c0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2d6d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d6e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2d6f0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2d700 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2d710 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2d720 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2d730 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2d740 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2d750 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2d760 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2d770 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2d780 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2d790 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2d7a0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2d7b0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2d7c0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2d7d0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2d7e0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2d7f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2d800 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2d810 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2d820 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2d830 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2d840 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2d850 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2d860 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2d870 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2d880 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2d890 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2d8a0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2d8b0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2d8c0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2d8d0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2d8e0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2d8f0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2d900 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2d910 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2d920 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2d930 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2d940 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2d950 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2d960 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2d970 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2d980 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2d990 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2d9a0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2d9b0 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2d9c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2d9d0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2d9e0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2d9f0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2da00 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2da10 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2da20 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2da30 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2da40 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2da50 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2da60 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2da70 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2da80 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2da90 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2daa0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2dab0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2dac0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2dad0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2dae0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2daf0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2db00 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2db10 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2db20 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2db30 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2db40 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2db50 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2db60 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2db70 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2db80 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2db90 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2dba0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2dbb0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2dbc0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2dbd0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2dbe0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2dbf0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2dc00 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2dc10 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2dc20 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2dc30 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2dc40 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2dc50 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2dc60 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2dc70 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2dc80 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2dc90 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2dca0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2dcb0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2dcc0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2dcd0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2dce0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2dcf0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2dd00 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2dd10 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2dd20 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2dd30 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2dd40 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2dd50 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2dd60 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2dd70 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2dd80 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2dd90 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2dda0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2ddb0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2ddc0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2ddd0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2dde0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2ddf0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2de00 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2de10 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2de20 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2de30 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2de40 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2de50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2de60 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2de70 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2de80 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2de90 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2dea0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2deb0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2dec0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2ded0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2dee0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2def0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2df00 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2df10 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2df20 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2df30 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2df40 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2df50 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2df60 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2df70 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2df80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2df90 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2dfa0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2dfb0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2dfc0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2dfd0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2dfe0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2dff0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2e000 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2e010 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2e020 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e030 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2e040 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2e050 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2e060 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2e070 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2e080 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2e090 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2e0a0 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2e0b0 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2e0c0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2e0d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e0e0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2e0f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2e100 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2e110 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2e120 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2e130 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2e140 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2e150 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2e160 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2e170 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2e180 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2e190 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2e1a0 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2e1b0 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2e1c0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2e1d0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2e1e0 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2e1f0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2e200 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2e210 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2e220 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2e230 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2e240 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2e250 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2e260 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2e270 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2e280 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2e290 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2e2a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2e2b0 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2e2c0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2e2d0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2e2e0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2e2f0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2e300 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2e310 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2e320 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2e330 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2e340 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2e350 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2e360 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2e370 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2e380 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2e390 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2e3a0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2e3b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2e3c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2e3d0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2e3e0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2e3f0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2e400 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2e410 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2e420 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2e430 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2e440 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2e450 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2e460 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2e470 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2e480 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2e490 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2e4a0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2e4b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2e4c0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2e4d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2e4e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2e4f0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2e500 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2e510 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2e520 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2e530 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e540 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2e550 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2e560 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2e570 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2e580 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2e590 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2e5a0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2e5b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2e5c0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2e5d0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2e5e0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2e5f0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2e600 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2e610 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2e620 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54  esult set.** MET
2e630 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e640 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2e650 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2e660 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2e670 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2e680 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2e690 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
2e6a0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2e6b0 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
2e6c0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2e6d0 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
2e6e0 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
2e6f0 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
2e700 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
2e710 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
2e720 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2e730 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
2e740 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
2e750 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
2e760 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
2e770 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
2e780 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
2e790 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2e7a0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
2e7b0 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
2e7c0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2e7d0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
2e7e0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2e7f0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2e800 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
2e810 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
2e820 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2e830 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2e840 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
2e850 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2e860 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
2e870 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
2e880 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2e890 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2e8a0 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
2e8b0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
2e8c0 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
2e8d0 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
2e8e0 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
2e8f0 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
2e900 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
2e910 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
2e920 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
2e930 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
2e940 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
2e950 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
2e960 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2e970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2e980 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
2e990 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
2e9a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2e9b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e9c0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
2e9d0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
2e9e0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
2e9f0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
2ea00 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
2ea10 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
2ea20 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
2ea30 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
2ea40 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
2ea50 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2ea60 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
2ea70 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
2ea80 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
2ea90 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
2eaa0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
2eab0 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
2eac0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2ead0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
2eae0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
2eaf0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
2eb00 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
2eb10 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
2eb20 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
2eb30 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
2eb40 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
2eb50 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
2eb60 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
2eb70 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
2eb80 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
2eb90 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2eba0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
2ebb0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
2ebc0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
2ebd0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
2ebe0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
2ebf0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
2ec00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
2ec10 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
2ec20 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
2ec30 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2ec40 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
2ec50 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
2ec60 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2ec70 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
2ec80 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
2ec90 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
2eca0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
2ecb0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
2ecc0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
2ecd0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
2ece0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
2ecf0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2ed00 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
2ed10 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2ed20 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2ed30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2ed40 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2ed50 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2ed60 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2ed70 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2ed80 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2ed90 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2eda0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2edb0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2edc0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2edd0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2ede0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2edf0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2ee00 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2ee10 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2ee20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ee30 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2ee40 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2ee50 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2ee60 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2ee70 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2ee80 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2ee90 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2eea0 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2eeb0 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2eec0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2eed0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2eee0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2eef0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2ef00 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2ef10 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2ef20 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2ef30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2ef40 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2ef50 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2ef60 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2ef70 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2ef80 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2ef90 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2efa0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2efb0 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2efc0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2efd0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2efe0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2eff0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2f000 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2f010 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2f020 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2f030 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2f040 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2f050 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f060 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2f070 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2f080 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2f090 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2f0a0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2f0b0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2f0c0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2f0d0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2f0e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f0f0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2f100 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2f110 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2f120 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2f130 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2f140 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2f150 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2f160 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2f170 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2f180 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2f190 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2f1a0 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2f1b0 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2f1c0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2f1d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2f1e0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2f1f0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2f200 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2f210 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2f230 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2f240 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2f250 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2f260 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2f270 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2f280 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2f290 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2f2a0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2f2b0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2f2c0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2f2d0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2f2e0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2f2f0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2f300 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2f310 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2f320 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2f330 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2f340 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2f350 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2f360 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2f370 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2f380 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2f390 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2f3a0 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2f3b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2f3c0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2f3d0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2f3e0 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2f3f0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2f400 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2f410 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2f420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f430 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2f440 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2f450 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2f460 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2f470 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2f480 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2f490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f4a0 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2f4b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2f4c0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2f4d0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2f4e0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2f4f0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2f500 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2f510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f520 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2f530 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2f540 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2f550 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2f560 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2f570 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f580 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2f590 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2f5a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2f5b0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2f5c0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2f5d0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2f5e0 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2f5f0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2f600 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2f610 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2f620 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2f630 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2f640 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2f650 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2f660 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2f670 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2f680 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2f690 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2f6a0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2f6b0 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2f6c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2f6d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2f6e0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2f6f0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2f700 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f710 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2f720 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2f730 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2f740 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2f750 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2f760 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2f770 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2f780 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2f790 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2f7a0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2f7b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f7c0 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2f7d0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2f7e0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2f7f0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2f800 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2f810 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2f820 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2f830 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2f840 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2f850 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2f860 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f870 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2f880 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2f890 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2f8a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2f8b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2f8c0 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f8d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f8e0 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2f8f0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2f900 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2f910 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2f920 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2f930 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2f940 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2f950 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f960 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2f970 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f980 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2f990 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2f9a0 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2f9b0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2f9c0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2f9d0 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2f9e0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2f9f0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2fa00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fa10 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2fa20 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2fa30 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2fa40 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2fa50 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2fa60 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2fa70 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2fa80 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2fa90 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2faa0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  ointer..**.** <b
2fab0 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54  >Warning:</b> ^T
2fac0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2fad0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2fae0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2faf0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2fb00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2fb10 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20  ue] object.  In 
2fb20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  a multithreaded 
2fb30 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20  environment,.** 
2fb40 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2fb50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2fb60 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  ect may only be 
2fb70 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68  used safely with
2fb80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2fb90 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
2fba0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2fbb0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
2fbc0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
2fbd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2fbe0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2fbf0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2fc00 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2fc10 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
2fc20 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
2fc30 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
2fc40 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2fc50 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
2fc60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2fc70 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2fc80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fc90 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65  bytes()], the be
2fca0 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68  havior is not th
2fcb0 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20  readsafe..**.** 
2fcc0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2fcd0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
2fce0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
2fcf0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
2fd00 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
2fd10 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2fd20 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2fd30 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2fd40 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2fd50 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2fd60 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2fd70 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2fd80 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2fd90 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2fda0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2fdb0 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
2fdc0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2fdd0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2fde0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2fdf0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2fe00 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2fe10 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2fe20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2fe30 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2fe40 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2fe50 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2fe60 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2fe70 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2fe80 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2fe90 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2fea0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2feb0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2fec0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2fed0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2fee0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2fef0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2ff00 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2ff10 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2ff20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2ff30 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2ff40 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
2ff50 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2ff60 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2ff70 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2ff80 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
2ff90 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
2ffa0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2ffb0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2ffc0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2ffd0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
2ffe0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2fff0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
30000 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
30010 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
30020 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
30030 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
30040 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
30050 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
30060 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
30070 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
30080 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
30090 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
300a0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
300b0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
300c0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
300d0 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
300e0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
300f0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
30100 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
30110 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
30120 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
30130 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
30140 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
30150 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
30160 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
30170 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
30180 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
30190 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
301a0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
301b0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
301c0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
301d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
301e0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
301f0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
30200 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
30210 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
30220 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
30230 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
30240 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
30250 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
30260 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
30270 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
30280 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
30290 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
302a0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
302b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
302c0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
302d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
302e0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
302f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30300 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
30310 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
30320 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
30330 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
30340 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
30350 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
30360 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
30370 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
30380 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
30390 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
303a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
303b0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
303c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
303d0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
303e0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
303f0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
30400 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
30410 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
30420 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
30430 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
30440 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
30450 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
30460 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
30470 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
30480 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30490 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
304a0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
304b0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
304c0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
304d0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
304e0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
304f0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
30500 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
30510 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
30520 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
30530 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
30540 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
30550 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
30560 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
30570 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
30580 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
30590 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
305a0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
305b0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
305c0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
305d0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
305e0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
305f0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
30600 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
30610 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
30620 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
30630 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
30640 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
30650 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
30660 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
30670 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
30680 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
30690 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
306a0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
306b0 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
306c0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
306d0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
306e0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
306f0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
30700 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
30710 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  st policy is to 
30720 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
30730 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
30740 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
30750 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
30760 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
30770 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
30780 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
30790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
307a0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
307b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
307c0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
307d0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
307e0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
307f0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
30800 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
30810 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
30820 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30830 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
30840 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
30850 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
30860 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
30870 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
30880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30890 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
308a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
308b0 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
308c0 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
308d0 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
308e0 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
308f0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
30900 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
30910 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
30920 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
30930 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
30940 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
30950 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
30960 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
30970 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
30980 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30990 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
309a0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
309b0 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
309c0 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
309d0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
309e0 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
309f0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
30a00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30a10 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
30a20 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
30a30 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
30a40 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
30a50 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
30a60 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
30a70 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
30a80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
30a90 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30aa0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
30ab0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
30ac0 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
30ad0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
30ae0 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
30af0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
30b00 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
30b10 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74  lly.  Do <em>not
30b20 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70  </em> pass the p
30b30 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
30b40 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
30b50 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
30b60 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
30b70 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
30b80 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
30b90 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
30ba0 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
30bb0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
30bc0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
30bd0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
30be0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
30bf0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
30c00 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
30c10 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
30c20 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
30c30 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
30c40 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
30c50 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
30c60 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
30c70 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
30c80 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
30c90 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
30ca0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
30cb0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
30cc0 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
30cd0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
30ce0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
30cf0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30d00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
30d10 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
30d20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30d30 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
30d40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
30d50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30d60 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
30d70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
30d80 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
30d90 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
30da0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
30db0 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
30dc0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30dd0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
30de0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
30df0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
30e00 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
30e10 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
30e20 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
30e30 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
30e40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30e50 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30e60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30e70 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30e80 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
30e90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30ea0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
30eb0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
30ec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
30ed0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
30ee0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
30ef0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
30f00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
30f10 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
30f20 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
30f30 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a  t.** DESTRUCTOR:
30f40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30f50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30f60 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
30f70 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
30f80 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
30f90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
30fa0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
30fb0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
30fc0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
30fd0 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
30fe0 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
30ff0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
31000 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
31010 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
31020 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31030 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
31040 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
31050 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
31060 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
31070 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
31080 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
31090 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
310a0 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
310b0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
310c0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
310d0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
310e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
310f0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
31100 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
31110 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
31120 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
31130 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
31140 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31150 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
31160 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
31170 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
31180 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
31190 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
311a0 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
311b0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
311c0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
311d0 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
311e0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
311f0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
31200 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
31210 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
31220 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
31230 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
31240 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
31250 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
31260 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
31270 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
31280 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
31290 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
312a0 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
312b0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
312c0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
312d0 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
312e0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
312f0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
31300 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
31310 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
31320 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
31330 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
31340 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
31350 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
31360 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
31370 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
31380 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
31390 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
313a0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
313b0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
313c0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
313d0 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
313e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
313f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
31400 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31410 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
31420 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
31430 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  bject.** METHOD:
31440 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
31450 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
31460 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
31470 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
31480 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
31490 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
314a0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
314b0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
314c0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
314d0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
314e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
314f0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
31500 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
31510 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
31520 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
31530 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
31540 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
31550 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
31560 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
31570 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
31580 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
31590 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
315a0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
315b0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
315c0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
315d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
315e0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
315f0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
31600 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
31610 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
31620 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
31630 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
31640 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
31650 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31660 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
31670 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
31680 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
31690 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
316a0 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
316b0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
316c0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
316d0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
316e0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
316f0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
31700 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
31710 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
31720 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
31730 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
31740 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31750 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
31760 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
31770 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
31780 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
31790 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
317a0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
317b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
317c0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
317d0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
317e0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
317f0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
31800 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
31810 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
31820 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
31830 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
31840 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
31850 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
31860 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
31870 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
31880 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
31890 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
318a0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
318b0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
318c0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
318d0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
318e0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
318f0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
31900 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31910 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
31920 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
31930 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
31940 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
31950 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
31960 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
31970 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
31980 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
31990 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
319a0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
319b0 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
319c0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
319d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
319e0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
319f0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
31a00 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
31a10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
31a20 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
31a30 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
31a40 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
31a50 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
31a60 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
31a70 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
31a80 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
31a90 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
31aa0 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
31ab0 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
31ac0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
31ad0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
31ae0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
31af0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
31b00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
31b10 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
31b20 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
31b30 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
31b40 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
31b50 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
31b60 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
31b70 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
31b80 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
31b90 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
31ba0 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
31bb0 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
31bc0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
31bd0 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
31be0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
31bf0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
31c00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
31c10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
31c20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
31c30 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
31c40 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
31c50 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
31c60 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
31c70 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
31c80 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
31c90 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
31ca0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
31cb0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
31cc0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
31cd0 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
31ce0 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
31cf0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
31d00 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
31d10 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
31d20 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
31d30 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
31d40 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
31d50 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
31d60 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
31d70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
31d80 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
31d90 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
31da0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
31db0 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
31dc0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
31dd0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
31de0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
31df0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
31e00 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
31e10 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
31e20 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
31e30 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
31e40 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
31e50 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
31e60 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
31e70 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
31e80 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
31e90 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
31ea0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
31eb0 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
31ec0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
31ed0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
31ee0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
31ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
31f00 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
31f10 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
31f20 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
31f30 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
31f40 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
31f50 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
31f60 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
31f70 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
31f80 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
31f90 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
31fa0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
31fb0 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
31fc0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
31fd0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
31fe0 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
31ff0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
32000 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
32010 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
32020 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
32030 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
32040 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
32050 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
32060 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
32070 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
32080 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
32090 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
320a0 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
320b0 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
320c0 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
320d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
320e0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
320f0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
32100 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
32110 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
32120 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
32130 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
32140 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
32150 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
32160 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
32170 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32180 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
32190 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
321a0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
321b0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
321c0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
321d0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
321e0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
321f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
32200 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
32210 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
32220 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
32230 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
32240 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
32250 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
32260 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
32270 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
32280 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
32290 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
322a0 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
322b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
322c0 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
322d0 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
322e0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
322f0 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
32300 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
32310 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
32320 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
32330 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
32340 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
32350 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
32360 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
32370 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
32380 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
32390 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
323a0 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
323b0 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
323c0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
323d0 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
323e0 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
323f0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
32400 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
32410 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
32420 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
32430 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32440 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
32450 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
32460 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
32470 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
32480 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
32490 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
324a0 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
324b0 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
324c0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
324d0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
324e0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
324f0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
32500 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
32510 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
32520 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
32530 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
32540 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
32550 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
32560 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
32570 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
32580 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
32590 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
325a0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
325b0 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
325c0 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
325d0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
325e0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
325f0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
32600 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
32610 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
32620 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
32630 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
32640 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
32650 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
32660 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
32670 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
32680 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
32690 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
326a0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
326b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
326c0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
326d0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
326e0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
326f0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
32700 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
32710 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
32720 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
32730 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
32740 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
32750 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
32760 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
32770 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
32780 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
32790 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
327a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
327b0 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
327c0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
327d0 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
327e0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
327f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32800 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
32810 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
32820 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
32830 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
32840 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
32850 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
32860 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
32870 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
32880 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
32890 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
328a0 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
328b0 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
328c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
328d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
328e0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
328f0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
32900 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
32910 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
32920 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
32930 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
32940 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
32950 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
32960 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
32970 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
32980 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
32990 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
329a0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
329b0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
329c0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
329d0 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
329e0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
329f0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
32a00 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
32a10 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
32a20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
32a30 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
32a40 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
32a50 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
32a60 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
32a70 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
32a80 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
32a90 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
32aa0 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
32ab0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
32ac0 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
32ad0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
32ae0 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
32af0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
32b00 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
32b10 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
32b20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
32b30 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
32b40 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
32b50 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
32b60 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
32b70 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
32b80 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
32b90 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
32ba0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
32bb0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
32bc0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
32bd0 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
32be0 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
32bf0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
32c00 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
32c10 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
32c20 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
32c30 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
32c40 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
32c50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32c60 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
32c70 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
32c80 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
32c90 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
32ca0 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
32cb0 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
32cc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
32cd0 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
32ce0 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
32cf0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
32d00 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
32d10 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
32d20 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
32d30 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
32d40 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
32d50 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
32d60 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
32d70 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
32d80 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
32d90 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
32da0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
32db0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32dc0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
32dd0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
32de0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
32df0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
32e00 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
32e10 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
32e20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32e30 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
32e40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32e50 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
32e60 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
32e70 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
32e80 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
32e90 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
32ea0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
32eb0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
32ec0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32ed0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
32ee0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
32ef0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32f00 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
32f10 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
32f20 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
32f30 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
32f40 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
32f50 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
32f60 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
32f70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
32f80 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
32f90 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
32fa0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
32fb0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
32fc0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
32fd0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
32fe0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
32ff0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
33000 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33020 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
33030 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
33040 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
33050 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
33060 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33070 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
33080 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
33090 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
330a0 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
330b0 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
330c0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
330d0 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
330e0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
330f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33100 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
33110 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37      /* IMP: R-37
33120 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65  514-35566 */.#de
33130 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
33140 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20  6LE        2    
33150 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d  /* IMP: R-03371-
33160 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65  37637 */.#define
33170 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
33180 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49         3    /* I
33190 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35  MP: R-51971-3415
331a0 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
331b0 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
331c0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
331d0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
331e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
331f0 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
33200 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63    5    /* Deprec
33210 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ated */.#define 
33220 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
33230 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
33240 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33250 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
33260 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33270 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a  Function Flags.*
33280 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
33290 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64  ants may be ORed
332a0 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74   together with t
332b0 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  he .** [SQLITE_U
332c0 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20  TF8 | preferred 
332d0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61  text encoding] a
332e0 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
332f0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ument.** to [sql
33300 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33310 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
33320 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33330 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
33340 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33350 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  nction_v2()]..*/
33360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33370 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20  DETERMINISTIC   
33380 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41   0x800../*.** CA
33390 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
333a0 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
333b0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
333c0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
333d0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
333e0 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
333f0 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
33400 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
33410 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
33420 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
33430 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
33440 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
33450 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
33460 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
33470 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
33480 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
33490 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e  unctions.  To en
334a0 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d  courage programm
334b0 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ers to avoid.** 
334c0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
334d0 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70   we will not exp
334e0 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64  lain what they d
334f0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
33500 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
33510 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
33520 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
33530 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
33540 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
33550 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
33560 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
33570 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
33580 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
33590 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
335a0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
335b0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
335c0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
335d0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
335e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
335f0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
33600 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
33610 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
33620 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
33630 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
33640 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
33650 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
33660 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
33670 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
33680 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
33690 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
336a0 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
336b0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
336c0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
336d0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
336e0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
336f0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
33700 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  ue.**.** The C-l
33710 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
33720 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
33730 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
33740 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
33750 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
33760 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
33770 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
33780 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
33790 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
337a0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a  or aggregate.  .
337b0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
337c0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
337d0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
337e0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
337f0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
33800 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
33810 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
33820 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
33830 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
33840 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
33850 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
33860 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
33870 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
33880 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
33890 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
338a0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
338b0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
338c0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
338d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
338e0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
338f0 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
33900 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33910 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
33920 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
33930 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
33940 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
33950 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
33960 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
33970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
33980 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
33990 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
339a0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
339b0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
339c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
339d0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
339e0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
339f0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
33a00 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
33a10 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
33a20 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
33a30 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
33a40 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
33a50 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
33a60 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
33a70 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
33a80 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
33a90 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
33aa0 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69  that these routi
33ab0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
33ac0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
33ad0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33ae0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
33af0 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
33b00 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
33b10 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
33b20 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
33b30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33b40 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33b50 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
33b60 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
33b70 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
33b80 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
33b90 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
33ba0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
33bb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33bc0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
33bd0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33be0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
33bf0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
33c00 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
33c10 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
33c20 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
33c30 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
33c40 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
33c50 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
33c60 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
33c70 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
33c80 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
33c90 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
33ca0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
33cb0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
33cc0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
33cd0 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
33ce0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
33cf0 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
33d00 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
33d10 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
33d20 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
33d30 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
33d40 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
33d50 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
33d60 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
33d70 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
33d80 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
33d90 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
33da0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
33db0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
33dc0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
33dd0 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
33de0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
33df0 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
33e00 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
33e10 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
33e20 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
33e30 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
33e40 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
33e50 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
33e60 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
33e70 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
33e80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
33e90 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33ea0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
33eb0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
33ec0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
33ed0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
33ee0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
33ef0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
33f00 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
33f10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
33f20 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
33f30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33f40 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
33f50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
33f60 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
33f70 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
33f80 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
33f90 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
33fa0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
33fb0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
33fc0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
33fd0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33fe0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
33ff0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
34000 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
34010 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
34020 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
34030 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
34040 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34050 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
34060 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
34070 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
34080 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
34090 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
340a0 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
340b0 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
340c0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
340d0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
340e0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
340f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
34100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34110 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
34120 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34130 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
34140 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
34150 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34160 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
34170 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
34180 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
34190 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
341a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
341b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
341c0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
341d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
341e0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
341f0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
34200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34210 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20  EF: Finding The 
34220 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56  Subtype Of SQL V
34230 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
34240 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
34250 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34260 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56  _value_subtype(V
34270 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
34280 6e 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66  ns the subtype f
34290 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63  or.** an [applic
342a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
342b0 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75  L function] argu
342c0 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62  ment V.  The sub
342d0 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  type.** informat
342e0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
342f0 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65  to pass a limite
34300 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74  d amount of cont
34310 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  ext from.** one 
34320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
34330 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68  another.  Use th
34340 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
34350 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20  t_subtype()].** 
34360 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74  routine to set t
34370 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74  he subtype for t
34380 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
34390 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  of an SQL functi
343a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
343b0 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66   makes no use of
343c0 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e   subtype itself.
343d0 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73    It merely pass
343e0 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a  es the subtype.*
343f0 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c  * from the resul
34400 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63  t of one [applic
34410 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
34420 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f  L function] into
34430 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66   the.** input of
34440 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73   another..*/.uns
34450 69 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65  igned int sqlite
34460 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28  3_value_subtype(
34470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34480 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34490 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20  : Copy And Free 
344a0 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
344b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
344c0 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  lue.**.** ^The s
344d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
344e0 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  (V) interface ma
344f0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
34500 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34510 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e  ].** object D an
34520 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
34530 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79  ter to that copy
34540 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
34550 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64  _value] returned
34560 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63  .** is a [protec
34570 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34580 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69  e] object even i
34590 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e  f the input is n
345a0 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ot..** ^The sqli
345b0 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29  te3_value_dup(V)
345c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
345d0 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20  ns NULL if V is 
345e0 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20  NULL or if a.** 
345f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
34600 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  n fails..**.** ^
34610 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
34620 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66  e_free(V) interf
34630 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71  ace frees an [sq
34640 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34650 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ect.** previousl
34660 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
34670 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
34680 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73  up()].  ^If V is
34690 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
346a0 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
346b0 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73  value_free(V) is
346c0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
346d0 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  p..*/.SQLITE_EXP
346e0 45 52 49 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65  ERIMENTAL sqlite
346f0 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
34700 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74  _value_dup(const
34710 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
34720 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
34730 45 4e 54 41 4c 20 76 6f 69 64 20 73 71 6c 69 74  ENTAL void sqlit
34740 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71  e3_value_free(sq
34750 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
34760 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34770 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
34780 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
34790 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
347a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
347b0 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** Implementatio
347c0 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  ns of aggregate 
347d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
347e0 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  e this.** routin
347f0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
34800 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67  mory for storing
34810 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
34820 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
34830 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
34840 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
34850 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69  t(C,N) routine i
34860 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72  s called .** for
34870 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
34880 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
34890 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f  , SQLite.** allo
348a0 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72  cates N of memor
348b0 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
348c0 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
348d0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
348e0 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d  .** to the new m
348f0 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e  emory. ^On secon
34900 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
34910 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
34920 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34930 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
34940 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
34950 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
34960 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  e,.** the same b
34970 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
34980 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72  d.  Sqlite3_aggr
34990 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
349a0 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63  is normally.** c
349b0 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  alled once for e
349c0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ach invocation o
349d0 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c  f the xStep call
349e0 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e  back and then on
349f0 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77  e.** last time w
34a00 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hen the xFinal c
34a10 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
34a20 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72  ed.  ^(When no r
34a30 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20  ows match.** an 
34a40 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c  aggregate query,
34a50 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c   the xStep() cal
34a60 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67  lback of the agg
34a70 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a  regate function.
34a80 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
34a90 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65  n is never calle
34aa0 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69  d and xFinal() i
34ab0 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79  s called exactly
34ac0 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f   once..** In tho
34ad0 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65  se cases, sqlite
34ae0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
34af0 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63  ext() might be c
34b00 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
34b10 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d   first time from
34b20 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29   within xFinal()
34b30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
34b40 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34b50 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
34b60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
34b70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a  NULL pointer .**
34b80 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c   when first call
34b90 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20  ed if N is less 
34ba0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
34bb0 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
34bc0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
34bd0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
34be0 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
34bf0 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
34c00 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
34c10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
34c20 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
34c30 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
34c40 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
34c50 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
34c60 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
34c70 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
34c80 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
34c90 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
34ca0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
34cb0 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
34cc0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
34cd0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
34ce0 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
34cf0 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
34d00 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57  allocation.)^  W
34d10 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c  ithin the xFinal
34d20 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73   callback, it is
34d30 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65   customary to se
34d40 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c  t.** N=0 in call
34d50 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  s to sqlite3_agg
34d60 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
34d70 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a  ,N) so that no .
34d80 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d  ** pointless mem
34d90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
34da0 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  occur..**.** ^SQ
34db0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
34dc0 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
34dd0 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
34de0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
34df0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
34e00 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
34e10 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
34e20 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
34e30 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
34e40 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
34e50 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
34e60 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
34e70 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
34e80 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
34e90 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
34ea0 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
34eb0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
34ec0 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
34ed0 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
34ee0 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
34ef0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
34f00 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
34f10 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
34f20 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
34f30 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
34f40 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
34f50 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
34f60 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
34f70 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34f80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34f90 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
34fa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34fb0 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
34fc0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
34fd0 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
34fe0 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  xt.**.** ^The sq
34ff0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
35000 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35010 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
35020 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
35030 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
35040 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
35050 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
35060 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
35070 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35080 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
35090 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
350a0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
350b0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
350c0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
350d0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
350e0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
350f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
35100 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
35110 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
35120 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
35130 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
35140 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35150 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
35160 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
35170 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
35180 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35190 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
351a0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
351b0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
351c0 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
351d0 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
351e0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
351f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
35200 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
35210 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
35220 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
35230 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
35240 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35250 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
35260 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
35270 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35280 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
35290 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
352a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
352b0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
352c0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
352d0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
352e0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
352f0 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
35300 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
35310 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
35320 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35330 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35340 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
35350 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45  liary Data.** ME
35360 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
35370 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ntext.**.** Thes
35380 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  e functions may 
35390 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d  be used by (non-
353a0 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66  aggregate) SQL f
353b0 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
353c0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
353d0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
353e0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
353f0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
35400 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
35410 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
35420 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
35430 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
35440 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
35450 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
35460 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
35470 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
35480 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
35490 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rved.  An exampl
354a0 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68  e.** of where th
354b0 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66  is might be usef
354c0 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c  ul is in a regul
354d0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
354e0 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  tching.** functi
354f0 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
35500 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
35510 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
35520 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  on can be stored
35530 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
35540 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
35550 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
35560 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73  ng.  .** Then as
35570 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74   long as the pat
35580 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61  tern string rema
35590 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a  ins the same,.**
355a0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   the compiled re
355b0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
355c0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
355d0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
355e0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
355f0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a   same function..
35600 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35610 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
35620 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35630 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
35640 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
35650 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
35660 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
35670 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
35680 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
35690 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
356a0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
356b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
356c0 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69  ion. ^If there i
356d0 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a  s no metadata.**
356e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
356f0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72   the function ar
35700 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c  gument, this sql
35710 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
35720 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
35730 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
35740 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
35750 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
35760 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
35770 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
35780 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f  P as metadata fo
35790 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
357a0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
357b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
357c0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75  d function.  ^Su
357d0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
357e0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
357f0 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65  _auxdata(C,N) re
35800 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20  turn P from the 
35810 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
35820 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35830 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c  ta(C,N,P,X) call
35840 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
35850 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20   is still valid 
35860 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68  or.** NULL if th
35870 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  e metadata has b
35880 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  een discarded..*
35890 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61  * ^After each ca
358a0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
358b0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
358c0 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f  X) where X is no
358d0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74  t NULL,.** SQLit
358e0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
358f0 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
35900 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72  ction X with par
35910 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79  ameter P exactly
35920 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74  .** once, when t
35930 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
35940 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c  iscarded..** SQL
35950 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64  ite is free to d
35960 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64  iscard the metad
35970 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c  ata at any time,
35980 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e   including: <ul>
35990 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68  .** <li> when th
359a0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
359b0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
359c0 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a  er changes, or.*
359d0 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c  * <li> when [sql
359e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
359f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
35a00 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ze()] is called 
35a10 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
35a20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f  SQL statement, o
35a30 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73  r.** <li> when s
35a40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35a50 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ta() is invoked 
35a60 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d  again on the sam
35a70 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a  e parameter, or.
35a80 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74  ** <li> during t
35a90 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69  he original sqli
35aa0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
35ab0 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65  ) call when a me
35ac0 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c  mory .**      al
35ad0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
35ae0 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a  ccurs. </ul>)^.*
35af0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61  *.** Note the la
35b00 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72  st bullet in par
35b10 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65  ticular.  The de
35b20 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a  structor X in .*
35b30 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
35b40 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d  xdata(C,N,P,X) m
35b50 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69  ight be called i
35b60 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
35b70 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  re the.** sqlite
35b80 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
35b90 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20 72  interface even r
35ba0 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73  eturns.  Hence s
35bb0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35bc0 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  ta().** should b
35bd0 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68  e called near th
35be0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e  e end of the fun
35bf0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
35c00 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20  tion and the.** 
35c10 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
35c20 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ntation should n
35c30 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20  ot make any use 
35c40 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71  of P after.** sq
35c50 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
35c60 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c  a() has been cal
35c70 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  led..**.** ^(In 
35c80 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
35c90 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
35ca0 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
35cb0 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75   calls for.** fu
35cc0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
35cd0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69  s that are compi
35ce0 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74  le-time constant
35cf0 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74  s, including lit
35d00 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
35d10 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  nd [parameters] 
35d20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20  and expressions 
35d30 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68  composed from th
35d40 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e same.)^.**.** 
35d50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
35d60 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
35d70 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
35d80 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
35d90 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
35da0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
35db0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
35dc0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
35dd0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
35de0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35df0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
35e00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
35e10 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
35e20 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
35e30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35e40 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
35e50 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
35e60 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
35e70 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
35e80 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
35e90 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
35ea0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
35eb0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
35ec0 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
35ed0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
35ee0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
35ef0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
35f00 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
35f10 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
35f20 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
35f30 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
35f40 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
35f50 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
35f60 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
35f70 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
35f80 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
35f90 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
35fa0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
35fb0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
35fc0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
35fd0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
35fe0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
35ff0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
36000 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
36010 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
36020 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
36030 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
36040 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
36050 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
36060 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
36070 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
36080 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
36090 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74   compilers..*/.t
360a0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
360b0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
360c0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
360d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
360e0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
360f0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
36100 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
36110 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
36120 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
36130 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
36140 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36150 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
36160 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
36170 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44  nction.** METHOD
36180 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
36190 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  t.**.** These ro
361a0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
361b0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
361c0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
361d0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
361e0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
361f0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
36200 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
36210 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
36220 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
36230 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
36240 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
36250 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
36260 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
36270 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
36280 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
36290 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
362a0 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
362b0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
362c0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
362d0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
362e0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
362f0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
36300 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
36310 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
36320 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
36330 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
36340 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
36350 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36360 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
36370 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
36380 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
36390 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
363a0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
363b0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
363c0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
363d0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
363e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
363f0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
36400 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
36410 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
36420 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
36430 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36440 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
36450 28 43 2c 4e 29 20 61 6e 64 20 73 71 6c 69 74 65  (C,N) and sqlite
36460 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
36470 62 36 34 28 43 2c 4e 29 0a 2a 2a 20 69 6e 74 65  b64(C,N).** inte
36480 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
36490 65 73 75 6c 74 20 6f 66 20 74 68 65 20 61 70 70  esult of the app
364a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
364b0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
364c0 2a 2a 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  ** a BLOB contai
364d0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 20 62 79  ning all zero by
364e0 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
364f0 69 6e 20 73 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e  in size..**.** ^
36500 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36510 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
36520 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
36530 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
36540 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36550 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
36560 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
36570 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
36580 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
36590 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
365a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
365b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
365c0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
365d0 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
365e0 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
365f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
36600 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
36610 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
36620 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
36630 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
36640 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
36650 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
36660 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
36670 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
36680 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36690 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
366a0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
366b0 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
366c0 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
366d0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
366e0 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
366f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36700 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
36710 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
36720 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
36730 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
36740 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
36750 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
36760 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
36770 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
36780 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
36790 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
367a0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
367b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
367c0 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
367d0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
367e0 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
367f0 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
36800 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
36810 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
36820 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
36830 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
36840 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
36850 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
36860 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
36870 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
36880 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
36890 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
368a0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
368b0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
368c0 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
368d0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
368e0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
368f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36900 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
36910 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
36920 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
36930 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
36940 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
36950 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
36960 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
36970 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
36980 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
36990 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
369a0 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
369b0 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
369c0 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
369d0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
369e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
369f0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
36a00 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
36a10 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
36a20 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
36a30 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
36a40 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
36a50 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
36a60 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
36a70 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
36a80 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
36a90 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
36aa0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
36ab0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
36ac0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
36ad0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
36ae0 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
36af0 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
36b00 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
36b10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36b20 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e  rror_toobig() in
36b30 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
36b40 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
36b50 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
36b60 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
36b70 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
36b80 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
36b90 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
36ba0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36bb0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e  error_nomem() in
36bc0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
36bd0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
36be0 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
36bf0 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
36c00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
36c10 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
36c20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36c30 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
36c40 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
36c50 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
36c60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36c70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
36c80 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
36c90 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
36ca0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
36cb0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
36cc0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
36cd0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
36ce0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
36cf0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
36d00 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
36d10 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36d20 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
36d30 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
36d40 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
36d50 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
36d60 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
36d70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36d80 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
36d90 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
36da0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
36db0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
36dc0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36dd0 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
36de0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36df0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
36e00 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
36e10 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
36e20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36e30 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
36e40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36e50 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
36e60 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
36e70 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
36e80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36e90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
36ea0 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
36eb0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
36ec0 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
36ed0 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
36ee0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
36ef0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
36f00 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
36f10 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
36f20 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54  pectively..** ^T
36f30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36f40 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74 65 72  t_text64() inter
36f50 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36f60 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
36f70 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  .** application-
36f80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36f90 20 74 6f 20 62 65 20 61 20 74 65 78 74 20 73 74   to be a text st
36fa0 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64  ring in an encod
36fb0 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69 65 64  ing.** specified
36fc0 20 62 79 20 74 68 65 20 66 69 66 74 68 20 28 61   by the fifth (a
36fd0 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d 65 74  nd last) paramet
36fe0 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74 20 62  er, which must b
36ff0 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c  e one.** of [SQL
37000 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
37010 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
37020 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
37030 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
37040 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b  ..** ^SQLite tak
37050 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
37060 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
37070 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
37080 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
37090 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
370a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
370b0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66  terfaces..** ^If
370c0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
370d0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
370e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
370f0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
37100 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
37110 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
37120 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
37130 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a   2nd parameter.*
37140 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
37150 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
37160 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  er..** ^If the 3
37170 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
37180 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
37190 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
371a0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
371b0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
371c0 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
371d0 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
371e0 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
371f0 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
37200 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
37210 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
37220 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
37230 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
37240 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20  lt.  If the 3rd 
37250 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
37260 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
37270 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68  it.** must be th
37280 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e  e byte offset in
37290 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  to the string wh
372a0 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
372b0 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20  inator would.** 
372c0 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74  appear if the st
372d0 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74  ring where NUL t
372e0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
372f0 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
37300 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  s occur.** in th
37310 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79  e string at a by
37320 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69  te offset that i
37330 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  s less than the 
37340 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64  value of the 3rd
37350 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74  .** parameter, t
37360 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
37370 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f  g string will co
37380 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
37390 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72  ULs and the.** r
373a0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
373b0 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f  ions operating o
373c0 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65  n strings with e
373d0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
373e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49  undefined..** ^I
373f0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
37400 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
37410 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
37420 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
37430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37440 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
37450 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
37460 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
37470 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
37480 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
37490 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
374a0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
374b0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
374c0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
374d0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
374e0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
374f0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
37500 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
37510 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
37520 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
37530 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
37540 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
37550 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
37560 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
37570 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
37580 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
37590 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
375a0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
375b0 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
375c0 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
375d0 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
375e0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
375f0 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
37600 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
37610 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
37620 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
37630 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
37640 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
37650 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
37660 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
37670 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
37680 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
37690 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
376a0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
376b0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
376c0 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
376d0 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
376e0 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
376f0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
37700 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
37710 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
37720 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37730 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
37740 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
37750 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
37760 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37770 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
37780 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
37790 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
377a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
377b0 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
377c0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
377d0 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
377e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
377f0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
37800 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
37810 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
37820 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
37830 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
37840 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
37850 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
37860 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
37870 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
37880 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
37890 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
378a0 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
378b0 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
378c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
378d0 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
378e0 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
378f0 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
37900 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
37910 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
37920 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
37930 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
37940 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37950 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
37960 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
37970 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
37980 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
37990 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
379a0 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
379b0 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
379c0 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
379d0 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
379e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
379f0 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
37a00 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
37a10 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
37a20 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
37a30 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
37a40 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
37a50 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
37a60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
37a70 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
37a80 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
37a90 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37aa0 73 75 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69  sult_blob64(sqli
37ab0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e  te3_context*,con
37ac0 73 74 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20  st void*,.      
37ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37ae0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 75 69 6e       sqlite3_uin
37af0 74 36 34 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  t64,void(*)(void
37b00 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
37b10 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
37b20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37b30 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
37b40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37b50 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
37b60 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
37b70 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
37b80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37b90 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
37ba0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
37bb0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
37bc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37bd0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
37be0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
37bf0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37c00 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
37c10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
37c20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
37c30 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
37c40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37c50 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
37c60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
37c70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37c80 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
37c90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
37ca0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
37cb0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
37cc0 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
37cd0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
37ce0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
37cf0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37d00 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
37d10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
37d20 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
37d30 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
37d40 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37d50 6c 74 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  lt_text64(sqlite
37d60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
37d70 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
37d80 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
37d90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37da0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
37db0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
37dc0 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64   encoding);.void
37dd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37de0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
37df0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37e00 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
37e10 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
37e20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37e30 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
37e40 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
37e50 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
37e60 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
37e70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37e80 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
37e90 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
37ea0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
37eb0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
37ec0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37ed0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
37ee0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
37ef0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
37f00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
37f10 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
37f20 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
37f30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  ;.int sqlite3_re
37f40 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  sult_zeroblob64(
37f50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37f60 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
37f70 20 6e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   n);.../*.** CAP
37f80 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
37f90 68 65 20 53 75 62 74 79 70 65 20 4f 66 20 41 6e  he Subtype Of An
37fa0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
37fb0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
37fc0 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54  _context.**.** T
37fd0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37fe0 74 5f 73 75 62 74 79 70 65 28 43 2c 54 29 20 66  t_subtype(C,T) f
37ff0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
38000 68 65 20 73 75 62 74 79 70 65 20 6f 66 0a 2a 2a  he subtype of.**
38010 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
38020 20 74 68 65 20 5b 61 70 70 6c 69 63 61 74 69 6f   the [applicatio
38030 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
38040 6e 63 74 69 6f 6e 5d 20 77 69 74 68 20 0a 2a 2a  nction] with .**
38050 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
38060 74 5d 20 43 20 74 6f 20 62 65 20 74 68 65 20 76  t] C to be the v
38070 61 6c 75 65 20 54 2e 20 20 4f 6e 6c 79 20 74 68  alue T.  Only th
38080 65 20 6c 6f 77 65 72 20 38 20 62 69 74 73 20 0a  e lower 8 bits .
38090 2a 2a 20 6f 66 20 74 68 65 20 73 75 62 74 79 70  ** of the subtyp
380a0 65 20 54 20 61 72 65 20 70 72 65 73 65 72 76 65  e T are preserve
380b0 64 20 69 6e 20 63 75 72 72 65 6e 74 20 76 65 72  d in current ver
380c0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 3b  sions of SQLite;
380d0 0a 2a 2a 20 68 69 67 68 65 72 20 6f 72 64 65 72  .** higher order
380e0 20 62 69 74 73 20 61 72 65 20 64 69 73 63 61 72   bits are discar
380f0 64 65 64 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d 62  ded..** The numb
38100 65 72 20 6f 66 20 73 75 62 74 79 70 65 20 62 79  er of subtype by
38110 74 65 73 20 70 72 65 73 65 72 76 65 64 20 62 79  tes preserved by
38120 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 69 6e   SQLite might in
38130 63 72 65 61 73 65 0a 2a 2a 20 69 6e 20 66 75 74  crease.** in fut
38140 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
38150 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
38160 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73  sqlite3_result_s
38170 75 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f 63  ubtype(sqlite3_c
38180 6f 6e 74 65 78 74 2a 2c 75 6e 73 69 67 6e 65 64  ontext*,unsigned
38190 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
381a0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
381b0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
381c0 75 65 6e 63 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  uences.** METHOD
381d0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
381e0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
381f0 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
38200 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
38210 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
38220 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
38230 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38240 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
38250 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
38260 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
38270 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
38280 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
38290 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
382a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
382b0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
382c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
382d0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
382e0 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
382f0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
38300 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
38310 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
38320 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
38330 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
38340 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
38350 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
38360 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
38370 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
38380 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
38390 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
383a0 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
383b0 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
383c0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
383d0 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
383e0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
383f0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
38400 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
38410 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
38420 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
38430 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
38440 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
38450 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
38460 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
38470 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
38480 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
38490 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
384a0 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
384b0 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
384c0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
384d0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
384e0 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
384f0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
38500 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
38510 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
38520 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
38530 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
38540 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
38550 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
38560 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
38570 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
38580 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
38590 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
385a0 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
385b0 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
385c0 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
385d0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
385e0 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
385f0 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
38600 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
38610 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  at is passed.** 
38620 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
38630 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
38640 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
38650 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
38660 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
38670 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61  th argument, xCa
38680 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69  llback, is a poi
38690 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c  nter to the coll
386a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a  ating function..
386b0 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c  ** ^Multiple col
386c0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
386d0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
386e0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  ed using the sam
386f0 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69  e name but.** wi
38700 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  th different eTe
38710 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73  xtRep parameters
38720 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c   and SQLite will
38730 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a   use whichever.*
38740 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  * function requi
38750 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
38760 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61  ount of data tra
38770 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20  nsformation..** 
38780 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63  ^If the xCallbac
38790 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  k argument is NU
387a0 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c  LL then the coll
387b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e