/ Hex Artifact Content
Login

Artifact 5f8113dbec74c6c093ead9930afb8c9fbd9f643d:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  eter of.** sqlit
39c0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
39d0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
39e0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
39f0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3a00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3a10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3a30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3a40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3a50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3a60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3a70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3a80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3a90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3aa0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3ab0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3ac0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3ad0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3af0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3b00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3b10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3b20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3b30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3b40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3b50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3b60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3b70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3b80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3b90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3ba0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3bb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3bc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3bd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3be0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3bf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3c10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3c20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3c30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3c40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3c50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3c60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3c70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3c80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3c90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3ca0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3cb0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3cc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3cd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3ce0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3cf0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3d20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3d50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3d60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3d70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3d80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3d90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3da0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3db0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3dc0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3dd0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3de0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3df0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3e00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3e10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3e20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3e30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3e40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3e50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3e60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3e70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3e80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3e90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3ea0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3eb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3ec0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ed0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3ee0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
3ef0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
3f00: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3f10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3f20: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
3f30: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
3f40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
3f50: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3f60: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
3f70: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
3f80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3f90: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3fa0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3fb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3fc0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3fd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fe0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ff0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4000: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4010: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4020: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4030: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4040: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4050: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4060: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4070: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
4080: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
4090: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
40a0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
40d0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
40e0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
40f0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4120: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4130: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4140: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4150: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4160: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4170: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41a0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
41b0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
41c0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
41f0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4200: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4210: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4220: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4230: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4240: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4250: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4260: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4270: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
4280: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
4290: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
42a0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
42b0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
42c0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
42d0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
42e0: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
42f0: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4300: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4310: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4320: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4330: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4340: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4350: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4360: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4370: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4380: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4390: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43a0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
43b0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
43c0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
43d0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
43e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
43f0: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4400: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4410: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4420: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4430: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4440: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4450: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4470: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4480: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4490: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44a0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
44b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
44c0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
44d0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
44e0: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
44f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4500: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4510: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4520: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4530: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4540: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4550: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4560: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4580: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4590: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45a0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
45b0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
45c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
45d0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
45e0: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
45f0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4600: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4620: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4630: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4640: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4650: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4660: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4670: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4680: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4690: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46b0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
46c0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
46d0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
46e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
46f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4700: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4710: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4720: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4730: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4760: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4770: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4780: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4790: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47a0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
47b0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
47c0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
47d0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
47e0: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
47f0: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4810: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4820: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4830: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4840: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4850: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4860: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4870: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4880: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48a0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
48b0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
48c0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
48d0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
48e0: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
48f0: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4900: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4920: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4930: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4940: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4960: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4970: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4980: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4990: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
49b0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
49c0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
49d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
49e0: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
49f0: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a00: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a10: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a20: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a30: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a40: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4a50: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4a60: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a70: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a80: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a90: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4aa0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4ab0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4ad0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4ae0: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4af0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b10: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4b20: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4b30: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b50: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4b60: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4b70: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4b80: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4ba0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4bb0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4bc0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4bd0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4be0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4bf0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4c00: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4c10: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4c20: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4c30: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4c40: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4c50: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4c60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4c70: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4c80: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4c90: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4ca0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4cb0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4cc0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4cd0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4ce0: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4cf0: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4d00: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4d10: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4d20: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4d30: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4d40: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4d50: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4d60: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4d70: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4d80: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4d90: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4da0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
4db0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
4dc0: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
4dd0: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
4de0: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
4df0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
4e00: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
4e10: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
4e20: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
4e30: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
4e40: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4e50: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
4e60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4e70: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
4e80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4e90: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4ea0: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
4eb0: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
4ec0: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
4ed0: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
4ee0: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
4ef0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
4f00: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
4f10: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
4f20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4f30: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f50: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4f60: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4f70: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4f90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fa0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
4fb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
4fd0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4fe0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
4ff0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5000: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5010: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5020: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5030: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5040: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5050: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5060: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
5070: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5080: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
5090: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50a0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
50b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50c0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
50d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50e0: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
50f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5100: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5120: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5130: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5140: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5160: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
5170: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5180: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
5190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51a0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
51b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51c0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5220: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5230: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5240: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5260: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
5270: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
5280: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
5290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52a0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
52b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52c0: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
52d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52e0: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
52f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5300: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5320: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5330: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5340: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
5350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5360: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
5370: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5380: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
5390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53a0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
53b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53c0: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
53d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53e0: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
53f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5400: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5420: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5430: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5440: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
5450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5460: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
5470: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5480: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
5490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54a0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
54b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54c0: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
54d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54e0: 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20  ERR_MMAP        
54f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5500: 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23  ERR | (24<<8)).#
5510: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5520: 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20  ERR_GETTEMPPATH 
5530: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5540: 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23  ERR | (25<<8)).#
5550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5560: 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  ERR_CONVPATH    
5570: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5580: 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23  ERR | (26<<8)).#
5590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55a0: 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20  ERR_VNODE       
55b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
55c0: 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23  ERR | (27<<8)).#
55d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55e0: 45 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20  ERR_AUTH        
55f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5600: 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23  ERR | (28<<8)).#
5610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5620: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5630: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5640: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
5650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5660: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
5670: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5680: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
5690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56a0: 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20  BUSY_SNAPSHOT   
56b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56c0: 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29  BUSY   |  (2<<8)
56d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56e0: 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50  _CANTOPEN_NOTEMP
56f0: 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45  DIR      (SQLITE
5700: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c  _CANTOPEN | (1<<
5710: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5720: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49  TE_CANTOPEN_ISDI
5730: 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  R          (SQLI
5740: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32  TE_CANTOPEN | (2
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5760: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55  LITE_CANTOPEN_FU
5770: 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51  LLPATH       (SQ
5780: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5790: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
57a0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57b0: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28  CONVPATH       (
57c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
57d0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
57e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
57f0: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20  _VTAB           
5800: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5810: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5830: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5840: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5850: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5870: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5880: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5890: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
58a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
58b0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
58c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
58d0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
58e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58f0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5900: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5910: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5920: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5930: 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b  E_ABORT_ROLLBACK
5940: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5950: 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29  E_ABORT | (2<<8)
5960: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43  _CONSTRAINT_CHEC
5980: 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  K        (SQLITE
5990: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31  _CONSTRAINT | (1
59a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59c0: 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51  COMMITHOOK   (SQ
59d0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59e0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
59f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a00: 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20  INT_FOREIGNKEY  
5a10: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a20: 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  INT | (3<<8)).#d
5a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a40: 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e  STRAINT_FUNCTION
5a50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a60: 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29  STRAINT | (4<<8)
5a70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e  _CONSTRAINT_NOTN
5a90: 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45  ULL      (SQLITE
5aa0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35  _CONSTRAINT | (5
5ab0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5ad0: 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51  PRIMARYKEY   (SQ
5ae0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5af0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
5b00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5b10: 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20  INT_TRIGGER     
5b20: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5b30: 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  INT | (7<<8)).#d
5b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5b50: 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20  STRAINT_UNIQUE  
5b60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b70: 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29  STRAINT | (8<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42  _CONSTRAINT_VTAB
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39  _CONSTRAINT | (9
5bc0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5bd0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5be0: 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51  ROWID        (SQ
5bf0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5c00: 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e  |(10<<8)).#defin
5c10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c20: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
5c30: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c40: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5c50: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c60: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
5c70: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c80: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5c90: 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47  e SQLITE_WARNING
5ca0: 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20  _AUTOINDEX      
5cb0: 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47   (SQLITE_WARNING
5cc0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5cd0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55  ne SQLITE_AUTH_U
5ce0: 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20  SER             
5cf0: 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c    (SQLITE_AUTH |
5d00: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5d10: 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f   SQLITE_OK_LOAD_
5d20: 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20  PERMANENTLY     
5d30: 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c  (SQLITE_OK | (1<
5d40: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5d50: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5d60: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5d70: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5d80: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5d90: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5da0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5db0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5dc0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5dd0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5de0: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5df0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5e00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5e10: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5e20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e30: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5e40: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5e50: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e60: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e80: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
5e90: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
5ea0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5eb0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5ec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ed0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
5ee0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5ef0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5f00: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f20: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5f30: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5f40: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f60: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5f70: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5f80: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fa0: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
5fb0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
5fc0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fe0: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5ff0: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
6000: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6010: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6030: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20  PEN_MEMORY      
6040: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20       0x00000080 
6050: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6060: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6070: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6080: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
6090: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
60a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
60b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60c0: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
60d0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
60e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
60f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6100: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
6110: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
6120: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6130: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6140: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
6150: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
6160: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6180: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
6190: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
61a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
61b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61c0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
61d0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
61e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
61f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6200: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
6210: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
6220: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6230: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6240: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
6250: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
6260: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6270: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6290: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
62a0: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
62b0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
62c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
62d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
62e0: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
62f0: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
6300: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6310: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6330: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
6340: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
6350: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6360: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6380: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
6390: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
63a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
63b0: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
63c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63d0: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
63e0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
63f0: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
6400: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
6410: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
6420: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
6430: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
6440: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
6450: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
6460: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6470: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
6480: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
6490: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
64a0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
64b0: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
64c0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
64d0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
64e0: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
64f0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6500: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
6510: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
6520: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6530: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6540: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6550: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6560: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6570: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6580: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6590: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
65a0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
65b0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
65c0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
65d0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
65e0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
65f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6600: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6610: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6620: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6630: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6640: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6650: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6660: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6670: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6680: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6690: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
66a0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
66b0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
66c0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
66d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
66e0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
66f0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6700: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
6710: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
6720: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
6730: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
6740: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
6750: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6760: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6770: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
6780: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
6790: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
67a0: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
67b0: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
67c0: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
67d0: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
67e0: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
67f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
6800: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
6810: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
6820: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
6830: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
6840: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
6850: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
6860: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6870: 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  nged.  The SQLIT
6880: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6890: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a  BLE_WHEN_OPEN.**
68a0: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74   flag indicate t
68b0: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
68c0: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
68d0: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
68e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
68f0: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6900: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6910: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6920: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6930: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
6940: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
6950: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
6960: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
6970: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6980: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6990: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
69a0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
69b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69c0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
69d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
69e0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
69f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6a10: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6a20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a30: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6a40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a60: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6a70: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a80: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
6a90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6aa0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
6ab0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
6ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ad0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
6ae0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6af0: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6b00: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b10: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6b20: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b40: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6b50: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b60: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6b70: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6b80: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
6b90: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
6ba0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6bb0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
6bc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
6bd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6be0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6bf0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6c00: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6c10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6c20: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6c30: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6c40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c50: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20  OCAP_IMMUTABLE  
6c60: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c70: 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  002000../*.** CA
6c80: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6c90: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6ca0: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6cb0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6cc0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6cd0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6ce0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
6cf0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
6d00: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6d10: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6d20: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6d30: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6d40: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6d50: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6d60: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6d70: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6d80: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6d90: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6da0: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6dc0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6dd0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6de0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6df0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
6e00: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6e10: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6e20: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6e30: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6e40: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6e50: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6e60: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6e70: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6e80: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6e90: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6ea0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6eb0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6ec0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6ed0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6ee0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6ef0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
6f00: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6f10: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6f20: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
6f30: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
6f40: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6f50: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6f60: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6f70: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6f80: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6f90: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6fa0: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6fb0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6fc0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6fd0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6fe0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
6ff0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
7000: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
7010: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
7020: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7030: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
7040: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
7050: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
7060: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7070: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7080: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
7090: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
70a0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
70b0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
70c0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
70d0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
70e0: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
70f0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
7100: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
7110: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
7120: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
7130: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
7140: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
7150: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
7160: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
7170: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7180: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
7190: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
71a0: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
71b0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
71c0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
71d0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
71e0: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
71f0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
7200: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
7210: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
7220: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
7230: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
7240: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
7250: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
7260: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
7270: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
7280: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7290: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
72a0: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
72b0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
72c0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
72d0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
72e0: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
72f0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
7300: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
7310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7320: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
7330: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
7340: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7350: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
7360: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
7370: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7380: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
7390: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
73a0: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
73b0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
73c0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
73d0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
73e0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
73f0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
7400: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
7410: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
7420: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
7430: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
7440: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
7450: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
7460: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
7470: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
7480: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
7490: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
74a0: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
74b0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
74c0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
74d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
74e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
74f0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
7500: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
7510: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
7520: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
7530: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
7540: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7550: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
7560: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
7570: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
7580: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7590: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
75a0: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
75b0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
75c0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
75d0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
75e0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
75f0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
7600: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
7610: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
7620: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7630: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
7640: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7650: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7660: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7670: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
7680: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
7690: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
76a0: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
76b0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
76c0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
76d0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
76e0: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
76f0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
7700: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7710: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7720: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7730: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7740: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7750: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7760: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7770: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7780: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7790: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
77a0: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
77b0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
77c0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
77d0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
77e0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
77f0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
7800: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7810: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7820: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7830: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7840: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7850: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7860: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7870: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7880: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7890: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
78a0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
78b0: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
78c0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
78d0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
78e0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
78f0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7900: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7910: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7920: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7930: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7940: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7950: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7960: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7970: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7980: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7990: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
79a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
79b0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
79c0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
79d0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
79e0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
79f0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
7a00: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7a10: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7a20: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7a30: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7a40: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7a50: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7a60: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7a70: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7a80: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7a90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7aa0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7ab0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7ac0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7ad0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7ae0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
7af0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7b00: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7b10: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7b20: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7b30: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7b40: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7b50: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7b60: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7b70: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7b80: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7b90: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7ba0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
7bb0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
7bc0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
7bd0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7be0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
7bf0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
7c00: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7c10: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7c20: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7c30: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7c40: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7c50: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7c60: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7c70: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7c80: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7c90: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7ca0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7cb0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7cc0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7cd0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7ce0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7cf0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
7d00: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7d10: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7d20: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7d30: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7d40: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7d50: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7d60: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7d70: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7d80: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7d90: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7da0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7db0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7dc0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7dd0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7de0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
7df0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
7e00: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7e10: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7e20: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7e30: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7e40: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7e50: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7e60: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7e70: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7e80: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7e90: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7ea0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7eb0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7ec0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7ed0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7ee0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
7ef0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
7f00: 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   [file control o
7f10: 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66  pcodes | list of
7f20: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
7f30: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
7f40: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
7f50: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
7f60: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
7f70: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
7f80: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
7f90: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
7fa0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
7fb0: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
7fc0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
7fd0: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
7fe0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
7ff0: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
8000: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
8010: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
8020: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
8030: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
8040: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
8050: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
8060: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
8070: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
8080: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
8090: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
80a0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
80b0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
80c0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
80d0: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
80e0: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
80f0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
8100: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8110: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
8120: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
8130: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
8140: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
8150: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
8160: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
8170: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8180: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
8190: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
81a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
81b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
81c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
81d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
81e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
81f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8200: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
8210: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8220: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
8230: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8240: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
8250: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8260: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
8270: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
8280: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8290: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
82a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
82b0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
82c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
82d0: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
82e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
82f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8300: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8310: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
8320: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
8330: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8340: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8350: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
8360: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
8370: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
8380: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
8390: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
83a0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
83b0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
83c0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
83d0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
83e0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
83f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8400: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
8410: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
8420: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
8430: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
8440: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
8450: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
8460: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
8470: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
8480: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
8490: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
84a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
84b0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
84c0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
84d0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
84e0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
84f0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
8500: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
8510: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
8520: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
8530: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
8540: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
8550: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
8560: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
8570: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
8580: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
8590: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
85a0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
85b0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
85c0: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
85d0: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
85e0: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
85f0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8600: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
8610: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
8620: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
8630: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
8640: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8650: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
8660: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
8670: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8680: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
8690: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
86a0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
86b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
86c0: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
86d0: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
86e0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
86f0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8700: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8710: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8720: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
8730: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8740: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8750: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
8760: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8770: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
8780: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
8790: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
87a0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
87b0: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
87c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87d0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
87e0: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
87f0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8800: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8810: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8820: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8830: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
8840: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
8850: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8860: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
8870: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
8880: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8890: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
88a0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
88b0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
88c0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
88d0: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
88e0: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
88f0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8900: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8910: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8920: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8930: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8940: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8950: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8960: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
8970: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
8980: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8990: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
89a0: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
89b0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
89c0: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
89d0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
89e0: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
89f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8a00: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8a10: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8a20: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8a30: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
8a40: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
8a50: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8a60: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
8a70: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
8a80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
8a90: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8aa0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8ab0: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
8ac0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8ad0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8ae0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
8af0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
8b00: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
8b10: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8b20: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8b30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8b40: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8b50: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8b60: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65   KEYWORDS: {file
8b70: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8b80: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  } {file control 
8b90: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  opcode}.**.** Th
8ba0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8bb0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8bc0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8bd0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
8be0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
8bf0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8c00: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8c10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8c20: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8c30: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rface..**.** <ul
8c40: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
8c50: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8c60: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8c70: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8c80: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8c90: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8ca0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8cb0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8cc0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8cd0: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8ce0: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8cf0: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8d00: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8d10: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8d20: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8d30: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8d40: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8d50: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8d60: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8d70: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8d80: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8d90: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8da0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8db0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8dc0: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8dd0: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73  g testing and is
8de0: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
8df0: 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  when the SQLITE_
8e00: 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  TEST.** compile-
8e10: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75  time option is u
8e20: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  sed..**.** <li>[
8e30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8e40: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8e50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8e60: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8e70: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
8e80: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8e90: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8ea0: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8eb0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8ec0: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8ed0: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8ee0: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8ef0: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8f00: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8f10: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8f20: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8f30: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8f40: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8f50: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8f60: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8f70: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8f80: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8f90: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8fa0: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8fb0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8fc0: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8fd0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8fe0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8ff0: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
9000: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
9010: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
9020: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
9030: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
9040: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
9050: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
9060: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
9070: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
9080: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
9090: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
90a0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
90b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
90c0: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
90d0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
90e0: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
90f0: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
9100: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
9110: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
9120: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
9130: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
9140: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
9150: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
9160: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
9170: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
9180: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
9190: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
91a0: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
91b0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
91c0: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
91d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
91e0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
91f0: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9210: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9220: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9230: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9240: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9250: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9260: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
9270: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9280: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9290: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
92a0: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
92b0: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
92c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
92d0: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
92e0: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
92f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9300: 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  AL_POINTER] opco
9310: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
9320: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9330: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9340: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9350: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
9360: 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  he journal file 
9370: 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b  (either.** the [
9380: 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
9390: 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d  ] or the [write-
93a0: 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20  ahead log]) for 
93b0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
93c0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
93d0: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
93e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
93f0: 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  E_POINTER]..**.*
9400: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9410: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
9420: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72  D]].** No longer
9430: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c   in use..**.** <
9440: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9450: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20  L_SYNC]].** The 
9460: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9470: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  NC] opcode is ge
9480: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9490: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ly by SQLite and
94a0: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20  .** sent to the 
94b0: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  VFS immediately 
94c0: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63  before the xSync
94d0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
94e0: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62  ed on a.** datab
94f0: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  ase file descrip
9500: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  tor. Or, if the 
9510: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
9520: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20  not invoked .** 
9530: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72  because the user
9540: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   has configured 
9550: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20  SQLite with .** 
9560: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
9570: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9580: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74  chronous=OFF] it
9590: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70   is invoked in p
95a0: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20  lace .** of the 
95b0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e  xSync method. In
95c0: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65   most cases, the
95d0: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
95e0: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a  t passed with.**
95f0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
9600: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65  ol is NULL. Howe
9610: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61  ver, if the data
9620: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69  base file is bei
9630: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20  ng synced.** as 
9640: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d  part of a multi-
9650: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c  database commit,
9660: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f   the argument po
9670: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65  ints to a nul-te
9680: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
9690: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
96a0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d  e transactions m
96b0: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69  aster-journal fi
96c0: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74  le name. VFSes t
96d0: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e  hat .** do not n
96e0: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
96f0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9700: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9710: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
9720: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20   .** should not 
9730: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
9740: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9750: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9760: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a  s doing so may .
9770: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ** disrupt the o
9780: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9790: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
97a0: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
97b0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
97c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
97d0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
97e0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
97f0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9800: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20  HASETWO] opcode 
9810: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
9820: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
9830: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f  e.** and sent to
9840: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61   the VFS after a
9850: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73   transaction has
9860: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20   been committed 
9870: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62  immediately.** b
9880: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ut before the da
9890: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b  tabase is unlock
98a0: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64  ed. VFSes that d
98b0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
98c0: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64  signal.** should
98d0: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
98e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
98f0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
9900: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73  d not call.** [s
9910: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9920: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
9930: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9940: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9950: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  the .** operatio
9960: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9970: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9980: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9990: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
99a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
99b0: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
99c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
99d0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
99e0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
99f0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
9a00: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
9a10: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
9a20: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
9a30: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
9a40: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9a50: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9a60: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9a70: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9a80: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9a90: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
9aa0: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
9ab0: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
9ac0: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
9ad0: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
9ae0: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
9af0: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
9b00: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
9b10: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
9b20: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
9b30: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
9b40: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9b50: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9b60: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9b70: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9b80: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9b90: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
9ba0: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
9bb0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
9bc0: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
9bd0: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
9be0: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
9bf0: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9c00: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9c10: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9c20: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9c30: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9c40: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9c50: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9c60: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9c70: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9c80: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9c90: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
9ca0: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
9cb0: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
9cc0: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
9cd0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
9ce0: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
9cf0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
9d00: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
9d10: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
9d20: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
9d30: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
9d40: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
9d50: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
9d60: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
9d70: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
9d80: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
9d90: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
9da0: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
9db0: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
9dc0: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
9dd0: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
9de0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9df0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9e00: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
9e10: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9e20: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
9e30: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9e40: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9e50: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
9e60: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
9e70: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
9e80: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9e90: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
9ea0: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
9eb0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
9ec0: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
9ed0: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
9ee0: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
9ef0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
9f00: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
9f10: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
9f20: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
9f30: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
9f40: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9f50: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
9f60: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
9f70: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
9f80: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
9f90: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
9fa0: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
9fb0: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
9fc0: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
9fd0: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
9fe0: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
9ff0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
a000: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
a010: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
a020: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
a030: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
a040: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
a050: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
a060: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
a070: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
a080: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
a090: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a0a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a0b0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a0c0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a0d0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a0e0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a0f0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a100: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
a110: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a120: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a130: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
a140: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a150: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a160: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a170: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a180: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a190: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a1a0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a1b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a1c0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a1d0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a1e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a1f0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a200: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a210: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a220: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a230: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a240: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a250: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a260: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a270: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a280: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a290: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a2a0: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a2b0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a2c0: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a2d0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a2e0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a2f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a300: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a310: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a320: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a330: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a340: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a350: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a360: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a370: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a380: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
a390: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a3a0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a3b0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a3c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
a3d0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
a3e0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a3f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
a400: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a410: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a420: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a430: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
a440: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
a450: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
a460: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
a470: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
a480: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
a490: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
a4a0: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
a4b0: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
a4c0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
a4d0: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
a4e0: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
a4f0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
a500: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
a510: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
a520: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a530: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
a540: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a550: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
a560: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
a570: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
a580: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
a590: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
a5a0: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
a5b0: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
a5c0: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
a5d0: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
a5e0: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
a5f0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
a600: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
a610: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
a620: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
a630: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
a640: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
a650: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
a660: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a670: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
a680: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a690: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
a6a0: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
a6b0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
a6c0: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
a6d0: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
a6e0: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
a6f0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
a700: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
a710: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
a720: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
a730: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
a740: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
a750: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
a760: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
a770: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
a780: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
a790: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
a7a0: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
a7b0: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
a7c0: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
a7d0: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
a7e0: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
a7f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a800: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d  TL_VFS_POINTER]]
a810: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a820: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
a830: 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  ER] opcode finds
a840: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
a850: 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b  e top-level.** [
a860: 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79  VFSes] currently
a870: 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20   in use.  ^(The 
a880: 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a  argument X in.**
a890: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
a8a0: 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f  ntrol(db,SQLITE_
a8b0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
a8c0: 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20  R,X) must be.** 
a8d0: 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65  of type "[sqlite
a8e0: 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69  3_vfs] **".  Thi
a8f0: 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73  s opcodes will s
a900: 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f  et *X.** to a po
a910: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
a920: 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a  -level VFS.)^.**
a930: 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65   ^When there are
a940: 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68   multiple VFS sh
a950: 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b  ims in the stack
a960: 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69  , this opcode fi
a970: 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72  nds the.** upper
a980: 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e  -most shim only.
a990: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a9a0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a9b0: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
a9c0: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
a9d0: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
a9e0: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
a9f0: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
aa00: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
aa10: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
aa20: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
aa30: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
aa40: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
aa50: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
aa60: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
aa70: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
aa80: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
aa90: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
aaa0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
aab0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
aac0: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
aad0: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
aae0: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
aaf0: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
ab00: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
ab10: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
ab20: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
ab30: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
ab40: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
ab50: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
ab60: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
ab70: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
ab80: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
ab90: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
aba0: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
abb0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
abc0: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
abd0: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
abe0: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
abf0: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
ac00: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
ac10: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
ac20: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
ac30: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
ac40: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
ac50: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
ac60: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
ac70: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
ac80: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
ac90: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
aca0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
acb0: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
acc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
acd0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ace0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
acf0: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
ad00: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
ad10: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
ad20: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
ad30: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
ad40: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
ad50: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
ad60: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
ad70: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
ad80: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
ad90: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
ada0: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
adb0: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
adc0: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
add0: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
ade0: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20  ed statement if 
adf0: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73  result string is
ae00: 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72   NULL, or that r
ae10: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a  eturns a copy.**
ae20: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
ae30: 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72  tring if the str
ae40: 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e  ing is non-NULL.
ae50: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
ae60: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ae70: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
ae80: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
ae90: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
aea0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
aeb0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
aec0: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
aed0: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
aee0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
aef0: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
af00: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
af10: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
af20: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
af30: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
af40: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
af50: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af60: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
af70: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
af80: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
af90: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
afa0: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
afb0: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
afc0: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
afd0: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
afe0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
aff0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b000: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b010: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b020: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b030: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
b040: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
b050: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
b060: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
b070: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
b080: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
b090: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
b0a0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
b0b0: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
b0c0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
b0d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
b0e0: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
b0f0: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
b100: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
b110: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
b120: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
b130: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
b140: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
b150: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
b160: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
b170: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
b180: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
b190: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
b1a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
b1b0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
b1c0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
b1d0: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
b1e0: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
b1f0: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
b200: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
b210: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
b220: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
b230: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
b240: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
b250: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
b260: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
b270: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
b280: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
b290: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
b2a0: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
b2b0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b2c0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b2d0: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
b2e0: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
b2f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b300: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
b310: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
b320: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
b330: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
b340: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
b350: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
b360: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
b370: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
b380: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
b390: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
b3a0: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
b3b0: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
b3c0: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
b3d0: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
b3e0: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
b3f0: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
b400: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
b410: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
b420: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
b430: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
b440: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
b450: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
b460: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
b470: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
b480: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
b490: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
b4a0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b4b0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
b4c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b4d0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b4e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b4f0: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
b500: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
b510: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b520: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
b530: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
b540: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
b550: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b560: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b570: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
b580: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
b590: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
b5a0: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
b5b0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
b5c0: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
b5d0: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
b5e0: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
b5f0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
b600: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
b610: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
b620: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
b630: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
b640: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
b650: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
b660: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
b670: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
b680: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
b690: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
b6a0: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
b6b0: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
b6c0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
b6d0: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
b6e0: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
b6f0: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
b700: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b710: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
b720: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b730: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
b740: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
b750: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
b760: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
b770: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
b780: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
b790: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
b7a0: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
b7b0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b7c0: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
b7d0: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
b7e0: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
b7f0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b800: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
b810: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
b820: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
b830: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
b840: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
b850: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
b860: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
b870: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
b880: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
b890: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
b8a0: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
b8b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b8c0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b8d0: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
b8e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
b8f0: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
b900: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
b910: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
b920: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
b930: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
b940: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
b950: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
b960: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
b970: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
b980: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
b990: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
b9a0: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
b9b0: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
b9c0: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
b9d0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b9e0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
b9f0: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
ba00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
ba10: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
ba20: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
ba30: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
ba40: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
ba50: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
ba60: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
ba70: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
ba80: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
ba90: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
baa0: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
bab0: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
bac0: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
bad0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
bae0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
baf0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
bb00: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
bb10: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
bb20: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bb30: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
bb40: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bb50: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
bb60: 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  ] is a signal to
bb70: 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74   the VFS layer t
bb80: 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20  hat it might.** 
bb90: 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20  be advantageous 
bba0: 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  to block on the 
bbb0: 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66  next WAL lock if
bbc0: 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74   the lock is not
bbd0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
bbe0: 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20  available.  The 
bbf0: 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73  WAL subsystem is
bc00: 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c  sues this signal
bc10: 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20   during rare.** 
bc20: 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e  circumstances in
bc30: 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20   order to fix a 
bc40: 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69  problem with pri
bc50: 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e  ority inversion.
bc60: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
bc70: 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c   should <em>not<
bc80: 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69  /em> use this fi
bc90: 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a  le-control..**.*
bca0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bcb0: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
bcc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bcd0: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
bce0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
bcf0: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
bd00: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
bd10: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
bd20: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
bd30: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
bd40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bd50: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a  ITE_FCNTL_RBU]].
bd60: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bd70: 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65  CNTL_RBU] opcode
bd80: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
bd90: 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  by the special V
bda0: 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68  FS used by.** th
bdb0: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
bdc0: 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72  only.  All other
bdd0: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
bde0: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
bdf0: 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f  ND for.** this o
be00: 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c  pcode.  .** </ul
be10: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
be20: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
be30: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
be40: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
be50: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
be60: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
be70: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
be80: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
be90: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
bea0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
beb0: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
bec0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34  O              4
bed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bee0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
bef0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
bf00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bf10: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
bf20: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
bf30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bf40: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
bf50: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
bf60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf70: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
bf80: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
bf90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bfa0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
bfb0: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
bfc0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bfd0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
bfe0: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
bff0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c000: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
c010: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
c020: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
c030: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
c040: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
c050: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
c060: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
c070: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
c080: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
c090: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
c0a0: 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53      14.#define S
c0b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
c0c0: 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20  HANDLER         
c0d0: 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51     15.#define SQ
c0e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
c0f0: 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20  ILENAME         
c100: 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
c110: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
c120: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
c130: 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   18.#define SQLI
c140: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20  TE_FCNTL_TRACE  
c150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c160: 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  19.#define SQLIT
c170: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
c180: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  D              2
c190: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c1a0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20  _FCNTL_SYNC     
c1b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
c1c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1d0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
c1e0: 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a  SETWO        22.
c1f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c200: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c210: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23  ANDLE       23.#
c220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c230: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20  NTL_WAL_BLOCK   
c240: 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64             24.#d
c250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c260: 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20  TL_ZIPVFS       
c270: 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65            25.#de
c280: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c290: 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20  L_RBU           
c2a0: 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66           26.#def
c2b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2c0: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20  _VFS_POINTER    
c2d0: 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69          27.#defi
c2e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c2f0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20  JOURNAL_POINTER 
c300: 20 20 20 20 20 20 20 32 38 0a 0a 2f 2a 20 64 65         28../* de
c310: 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a  precated names *
c320: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c330: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
c340: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
c350: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
c360: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
c370: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
c380: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
c390: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
c3a0: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
c3b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
c3c0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
c3d0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c    SQLITE_FCNTL_L
c3e0: 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a  AST_ERRNO.../*.*
c3f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
c400: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
c410: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
c420: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
c430: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
c440: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
c450: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
c460: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
c470: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
c480: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
c490: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
c4a0: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
c4b0: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
c4c0: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
c4d0: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
c4e0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
c4f0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
c500: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
c510: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
c520: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
c530: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
c540: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
c550: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
c560: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
c570: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c580: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
c590: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
c5a0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
c5b0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
c5c0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
c5d0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
c5e0: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
c5f0: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
c600: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
c610: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
c620: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
c630: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
c640: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
c650: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
c660: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
c670: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
c680: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
c690: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
c6a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
c6b0: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
c6c0: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
c6d0: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
c6e0: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
c6f0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
c700: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
c710: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
c720: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
c730: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
c740: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
c750: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
c760: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
c770: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
c780: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
c790: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
c7a0: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
c7b0: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
c7c0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
c7d0: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
c7e0: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
c7f0: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
c800: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
c810: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
c820: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
c830: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
c840: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
c850: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
c860: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
c870: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
c880: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
c890: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
c8a0: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
c8b0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
c8c0: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
c8d0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
c8e0: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
c8f0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
c900: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
c910: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
c920: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
c930: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
c940: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
c950: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
c960: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
c970: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
c980: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
c990: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
c9a0: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
c9b0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
c9c0: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
c9d0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
c9e0: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
c9f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
ca00: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
ca10: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
ca20: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
ca30: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
ca40: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
ca50: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
ca60: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
ca70: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
ca80: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
ca90: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
caa0: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
cab0: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
cac0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
cad0: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
cae0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
caf0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
cb00: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
cb10: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
cb20: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
cb30: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
cb40: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
cb50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
cb60: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
cb70: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
cb80: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
cb90: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
cba0: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
cbb0: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
cbc0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
cbd0: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
cbe0: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
cbf0: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
cc00: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
cc10: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
cc20: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
cc30: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
cc40: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
cc50: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
cc60: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
cc70: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
cc80: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
cc90: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
cca0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
ccb0: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
ccc0: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
ccd0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
cce0: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
ccf0: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
cd00: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
cd10: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
cd20: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
cd30: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
cd40: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
cd50: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
cd60: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
cd70: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
cd80: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
cd90: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
cda0: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
cdb0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
cdc0: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
cdd0: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
cde0: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
cdf0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
ce00: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
ce10: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
ce20: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
ce30: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
ce40: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
ce50: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
ce60: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
ce70: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
ce80: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
ce90: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
cea0: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
ceb0: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
cec0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
ced0: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
cee0: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
cef0: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
cf00: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
cf10: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
cf20: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
cf30: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
cf40: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
cf50: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
cf60: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
cf70: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
cf80: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
cf90: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
cfa0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
cfb0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
cfc0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
cfd0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
cfe0: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
cff0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
d000: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
d010: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
d020: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
d030: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
d040: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
d050: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
d060: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
d070: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
d080: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
d090: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
d0a0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
d0b0: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
d0c0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
d0d0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
d0e0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
d0f0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
d100: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
d110: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
d120: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d130: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d140: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
d150: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d160: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
d170: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d180: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
d190: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d1a0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
d1b0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
d1c0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
d1d0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
d1e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
d1f0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
d200: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d210: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
d220: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d230: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
d240: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
d250: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
d260: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
d270: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
d280: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
d290: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
d2a0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
d2b0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
d2c0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
d2d0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
d2e0: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
d2f0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
d300: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
d310: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
d320: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
d330: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
d340: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
d350: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
d360: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
d370: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
d380: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
d390: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
d3a0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
d3b0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
d3c0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
d3d0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
d3e0: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
d3f0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
d400: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
d410: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
d420: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
d430: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
d440: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
d450: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
d460: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
d470: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
d480: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
d490: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
d4a0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
d4b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
d4c0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
d4d0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
d4e0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
d4f0: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
d500: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
d510: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
d520: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
d530: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
d540: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
d550: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
d560: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
d570: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d580: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
d590: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
d5a0: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
d5b0: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
d5c0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
d5d0: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
d5e0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
d5f0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
d600: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
d610: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
d620: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
d630: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
d640: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
d650: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
d660: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
d670: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
d680: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
d690: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
d6a0: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
d6b0: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
d6c0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
d6d0: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
d6e0: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
d6f0: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
d700: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
d710: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
d720: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
d730: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
d740: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
d750: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
d760: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
d770: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
d780: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
d790: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
d7a0: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
d7b0: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
d7c0: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
d7d0: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
d7e0: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
d7f0: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
d800: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
d810: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
d820: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
d830: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
d840: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
d850: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
d860: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
d870: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
d880: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
d890: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
d8a0: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
d8b0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
d8c0: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
d8d0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
d8e0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
d8f0: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
d900: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
d910: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
d920: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
d930: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
d940: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
d950: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
d960: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
d970: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
d980: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
d990: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
d9a0: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
d9b0: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
d9c0: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
d9d0: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
d9e0: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
d9f0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
da00: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
da10: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
da20: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
da30: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
da40: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
da50: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
da60: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
da70: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
da80: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
da90: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
daa0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
dab0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
dac0: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
dad0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
dae0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
daf0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
db00: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
db10: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
db20: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
db30: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
db40: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
db50: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
db60: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
db70: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
db80: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
db90: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
dba0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
dbb0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
dbc0: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
dbd0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
dbe0: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
dbf0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
dc00: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
dc10: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
dc20: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
dc30: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
dc40: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
dc50: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
dc60: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
dc70: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
dc80: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
dc90: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
dca0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
dcb0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
dcc0: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
dcd0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
dce0: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
dcf0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
dd00: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
dd10: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
dd20: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dd30: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
dd40: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
dd50: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
dd60: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
dd70: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
dd80: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
dd90: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
dda0: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
ddb0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
ddc0: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
ddd0: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
dde0: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
ddf0: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
de00: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
de10: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
de20: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
de30: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
de40: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
de50: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
de60: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
de70: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
de80: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
de90: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
dea0: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
deb0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
dec0: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
ded0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
dee0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
def0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
df00: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
df10: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
df20: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
df30: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
df40: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
df50: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
df60: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
df70: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
df80: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
df90: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
dfa0: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
dfb0: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
dfc0: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
dfd0: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
dfe0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
dff0: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
e000: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
e010: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
e020: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
e030: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
e040: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
e050: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
e060: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
e070: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
e080: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
e090: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
e0a0: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
e0b0: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
e0c0: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
e0d0: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
e0e0: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
e0f0: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
e100: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
e110: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
e120: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
e130: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
e140: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
e150: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
e160: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
e170: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
e180: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
e190: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
e1a0: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
e1b0: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
e1c0: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
e1d0: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
e1e0: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
e1f0: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
e200: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
e210: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
e220: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
e230: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
e240: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
e250: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
e260: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
e270: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
e280: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
e290: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
e2a0: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
e2b0: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
e2c0: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
e2d0: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
e2e0: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
e2f0: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
e300: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
e310: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
e320: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
e330: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
e340: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
e350: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
e360: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
e370: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
e380: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
e390: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
e3a0: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
e3b0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
e3c0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
e3d0: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
e3e0: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
e3f0: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
e400: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
e410: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
e420: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
e430: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
e440: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
e450: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
e460: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
e470: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
e480: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
e490: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
e4a0: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
e4b0: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
e4c0: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
e4d0: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
e4e0: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
e4f0: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
e500: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
e510: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
e520: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
e530: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
e540: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
e550: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
e560: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
e570: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
e580: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
e590: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
e5a0: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
e5b0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
e5c0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
e5d0: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
e5e0: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
e5f0: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
e600: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
e610: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
e620: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e630: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
e640: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
e650: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
e660: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
e670: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
e680: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e690: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e6a0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
e6b0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
e6c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e6d0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e6e0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
e6f0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
e700: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
e710: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e720: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e730: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
e740: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
e750: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
e760: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e770: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
e780: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
e790: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
e7a0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
e7b0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
e7c0: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
e7d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
e7e0: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
e7f0: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
e800: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
e810: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
e820: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
e830: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
e840: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e850: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
e860: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
e870: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
e880: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
e890: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
e8a0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
e8b0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
e8c0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
e8d0: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
e8e0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
e8f0: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
e900: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
e910: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
e920: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
e930: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
e940: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
e950: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
e960: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
e970: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
e980: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
e990: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
e9a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e9b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
e9c0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
e9d0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
e9e0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
e9f0: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
ea00: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
ea10: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
ea20: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
ea30: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
ea40: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
ea50: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ea60: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ea70: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
ea80: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
ea90: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
eaa0: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
eab0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
eac0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ead0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
eae0: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
eaf0: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
eb00: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
eb10: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
eb20: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
eb30: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
eb40: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
eb50: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
eb60: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
eb70: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
eb80: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
eb90: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
eba0: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
ebb0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
ebc0: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
ebd0: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
ebe0: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
ebf0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
ec00: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
ec10: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
ec20: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
ec30: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
ec40: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
ec50: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
ec60: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
ec70: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
ec80: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
ec90: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
eca0: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
ecb0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
ecc0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
ecd0: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
ece0: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
ecf0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
ed00: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
ed10: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
ed20: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
ed30: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
ed40: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
ed50: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
ed60: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
ed70: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
ed80: 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
ed90: 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
eda0: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
edb0: 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
edc0: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
edd0: 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
ede0: 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
edf0: 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
ee00: 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
ee10: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
ee20: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
ee30: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
ee40: 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
ee50: 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
ee60: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
ee70: 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
ee80: 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
ee90: 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
eea0: 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
eeb0: 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
eec0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
eed0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
eee0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
eef0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
ef00: 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
ef10: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
ef20: 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
ef30: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
ef40: 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
ef50: 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
ef60: 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
ef70: 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
ef80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ef90: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
efa0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
efb0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
efc0: 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
efd0: 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
efe0: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
eff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f000: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
f010: 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
f020: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
f030: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
f040: 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
f050: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
f060: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
f070: 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
f080: 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
f090: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
f0a0: 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
f0b0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
f0c0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
f0d0: 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
f0e0: 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
f0f0: 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
f100: 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
f110: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
f120: 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
f130: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
f140: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
f150: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f160: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
f170: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
f180: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
f190: 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
f1a0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
f1b0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f1c0: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
f1d0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
f1e0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
f1f0: 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
f200: 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
f210: 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
f220: 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
f230: 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
f240: 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
f250: 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72  given on the cor
f260: 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
f270: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
f280: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
f290: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
f2a0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
f2b0: 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
f2c0: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
f2d0: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
f2e0: 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
f2f0: 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
f300: 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
f310: 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
f320: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
f330: 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
f340: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
f350: 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
f360: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
f370: 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
f380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f390: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
f3a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f3b0: 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
f3c0: 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
f3d0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
f3e0: 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
f3f0: 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
f400: 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
f410: 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
f420: 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
f430: 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
f440: 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
f450: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
f460: 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
f470: 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
f480: 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
f490: 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
f4a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f4b0: 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
f4c0: 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
f4d0: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
f4e0: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
f4f0: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
f500: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f510: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
f520: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
f530: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
f540: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
f550: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
f560: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
f570: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
f580: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
f590: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
f5a0: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
f5b0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
f5c0: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
f5d0: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
f5e0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
f5f0: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
f600: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
f610: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
f620: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
f630: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
f640: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
f650: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
f660: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
f670: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
f680: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
f690: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
f6a0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
f6b0: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
f6c0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
f6d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f6e0: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
f6f0: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
f700: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
f710: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
f720: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
f730: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f740: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
f750: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
f760: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f770: 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
f780: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
f790: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
f7a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
f7b0: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
f7c0: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
f7d0: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
f7e0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
f7f0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
f800: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f810: 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
f820: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
f830: 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
f840: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
f850: 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
f860: 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
f870: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
f880: 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
f890: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
f8a0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f8b0: 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
f8c0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
f8d0: 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
f8e0: 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
f8f0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
f900: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
f910: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
f920: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f930: 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
f940: 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
f950: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f960: 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
f970: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f980: 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
f990: 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
f9a0: 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
f9b0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
f9c0: 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
f9d0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
f9e0: 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
f9f0: 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
fa00: 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
fa10: 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
fa20: 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
fa30: 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
fa40: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
fa50: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
fa60: 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
fa70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
fa80: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
fa90: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
faa0: 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
fab0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
fac0: 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
fad0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
fae0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
faf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fb00: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
fb10: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
fb20: 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
fb30: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
fb40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fb50: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
fb60: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
fb70: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
fb80: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
fb90: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
fba0: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
fbb0: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
fbc0: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
fbd0: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
fbe0: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
fbf0: 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
fc00: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fc10: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
fc20: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
fc30: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
fc40: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
fc50: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
fc60: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
fc70: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
fc80: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
fc90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fca0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
fcb0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
fcc0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
fcd0: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
fce0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
fcf0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
fd00: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
fd10: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
fd20: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
fd30: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
fd40: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
fd50: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
fd60: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
fd70: 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
fd80: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
fd90: 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
fda0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
fdb0: 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
fdc0: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
fdd0: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
fde0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
fdf0: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
fe00: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
fe10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
fe20: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
fe30: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
fe40: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
fe50: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
fe60: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
fe70: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
fe80: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
fe90: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
fea0: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
feb0: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
fec0: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
fed0: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
fee0: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
fef0: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
ff00: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
ff10: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
ff20: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
ff30: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
ff40: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
ff50: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
ff60: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
ff70: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
ff80: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
ff90: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
ffa0: 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
ffb0: 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
ffc0: 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
ffd0: 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
ffe0: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
fff0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10000 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
10010 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
10020 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
10030 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
10040 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
10050 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
10060 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
10070 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
10080 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
10090 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
100a0 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
100b0 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
100c0 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
100d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
100e0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
100f0 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
10100 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
10110 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
10120 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
10130 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
10140 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
10150 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
10160 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
10170 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
10180 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
10190 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
101a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
101b0 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
101c0 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
101d0 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
101e0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
101f0 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
10200 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
10210 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
10220 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
10230 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
10240 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
10250 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
10260 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
10270 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
10280 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
10290 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
102a0 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
102b0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
102c0 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
102d0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
102e0 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
102f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
10300 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10310 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
10320 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
10330 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
10340 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
10350 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
10360 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
10370 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
10380 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
10390 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
103a0 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
103b0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
103c0 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
103d0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
103e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
103f0 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
10400 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
10410 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
10420 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
10430 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
10440 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
10450 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
10460 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
10470 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
10480 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
10490 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
104a0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
104b0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
104c0 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
104d0 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
104e0 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
104f0 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
10500 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
10510 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10520 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
10530 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
10540 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
10550 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
10560 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10570 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
10580 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
10590 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
105a0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
105b0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
105c0 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
105d0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
105e0 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
105f0 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
10600 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
10610 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
10620 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
10630 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
10640 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
10650 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
10660 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
10670 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
10680 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
10690 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
106a0 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
106b0 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
106c0 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
106d0 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
106e0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54  eeds..**.** <b>T
106f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
10700 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10710 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
10720 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
10730 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
10740 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
10750 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
10760 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
10770 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
10780 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
10790 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
107a0 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  g.</b>.**.** The
107b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
107c0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d  ) interface.** m
107d0 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
107e0 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
107f0 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
10800 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
10810 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10820 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
10830 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
10840 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
10850 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
10860 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
10870 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
10880 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
10890 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
108a0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
108b0 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
108c0 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
108d0 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
108e0 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
108f0 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
10900 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
10910 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
10920 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
10930 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
10940 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
10950 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
10960 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10970 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
10980 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
10990 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
109a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
109b0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
109c0 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
109d0 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
109e0 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
109f0 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10a00 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
10a10 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
10a20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10a30 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
10a40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
10a50 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
10a60 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10a70 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
10a80 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
10a90 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
10aa0 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
10ab0 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
10ac0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
10ad0 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
10ae0 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
10af0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10b00 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
10b10 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
10b20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
10b30 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
10b40 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10b50 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
10b60 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  nnections.** MET
10b70 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
10b80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
10b90 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
10ba0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
10bb0 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
10bc0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
10bd0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
10be0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
10bf0 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
10c00 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
10c10 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
10c20 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
10c30 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
10c40 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
10c50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10c60 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
10c70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10c80 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
10c90 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
10ca0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10cb0 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
10cc0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
10cd0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10ce0 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
10cf0 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
10d00 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
10d10 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
10d20 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
10d30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10d40 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
10d50 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
10d60 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
10d70 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
10d80 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
10d90 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
10da0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
10db0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
10dc0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
10dd0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
10de0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
10df0 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
10e00 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
10e10 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
10e20 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
10e30 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10e40 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
10e50 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
10e60 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
10e70 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10e80 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
10e90 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
10ea0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
10eb0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
10ec0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
10ed0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
10ee0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
10ef0 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
10f00 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
10f10 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
10f20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
10f30 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
10f40 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
10f50 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
10f60 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10f70 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
10f80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
10f90 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
10fa0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
10fb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10fc0 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
10fd0 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
10fe0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10ff0 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
11000 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
11010 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
11020 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11030 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
11040 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
11050 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
11060 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
11070 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
11080 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
11090 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
110a0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
110b0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
110c0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
110d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
110e0 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
110f0 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
11100 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
11110 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
11120 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
11130 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
11140 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
11150 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
11160 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
11170 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
11180 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
11190 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
111a0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
111b0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
111c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
111d0 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
111e0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
111f0 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
11200 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
11210 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
11220 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
11230 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
11240 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
11250 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
11260 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
11270 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
11280 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
11290 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
112a0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
112b0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
112c0 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
112d0 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
112e0 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
112f0 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
11300 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
11310 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
11320 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
11330 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
11340 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
11350 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
11360 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
11370 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
11380 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
11390 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
113a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
113b0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
113c0 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
113d0 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
113e0 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
113f0 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
11400 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
11410 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
11420 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
11430 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
11440 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
11450 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
11460 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
11470 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
11480 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
11490 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
114a0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
114b0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
114c0 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
114d0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
114e0 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
114f0 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
11500 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
11510 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
11520 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
11530 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
11540 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11550 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
11560 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
11570 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
11580 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
11590 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
115a0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
115b0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
115c0 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
115d0 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
115e0 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
115f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11600 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
11610 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
11620 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
11630 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
11640 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
11650 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
11660 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
11670 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11680 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
11690 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
116a0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
116b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
116c0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
116d0 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
116e0 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
116f0 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
11700 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
11710 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
11720 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
11730 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
11740 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
11750 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
11760 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
11770 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
11780 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
11790 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
117a0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
117b0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
117c0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
117d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
117e0 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
117f0 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
11800 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
11810 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
11820 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
11830 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
11840 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
11850 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
11860 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
11870 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
11880 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
11890 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
118a0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
118b0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
118c0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
118d0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
118e0 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
118f0 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
11900 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
11910 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
11920 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
11930 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
11940 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
11950 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11960 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
11970 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11980 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
11990 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
119a0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
119b0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
119c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
119d0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
119e0 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
119f0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11a00 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
11a10 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
11a20 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
11a30 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
11a40 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
11a50 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
11a60 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
11a70 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
11a80 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
11a90 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
11aa0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
11ab0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
11ac0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
11ad0 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
11ae0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
11af0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11b00 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
11b10 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
11b20 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11b30 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
11b40 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
11b50 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
11b60 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
11b70 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
11b80 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
11b90 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
11ba0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
11bb0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
11bc0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
11bd0 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
11be0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
11bf0 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
11c00 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
11c10 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
11c20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
11c30 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
11c40 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
11c50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
11c60 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
11c70 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
11c80 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
11c90 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
11ca0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
11cb0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
11cc0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11cd0 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
11ce0 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
11cf0 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
11d00 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11d10 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
11d20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
11d30 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
11d40 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
11d50 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
11d60 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
11d70 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
11d80 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
11d90 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
11da0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11db0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
11dc0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
11dd0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
11de0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
11df0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
11e00 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
11e10 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11e20 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
11e30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11e40 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
11e50 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
11e60 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
11e70 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
11e80 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
11e90 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
11ea0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11eb0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
11ec0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
11ed0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
11ee0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
11ef0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
11f00 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11f10 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
11f20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
11f30 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
11f40 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11f50 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
11f60 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
11f70 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
11f80 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
11f90 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
11fa0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
11fb0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
11fc0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
11fd0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
11fe0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11ff0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12000 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12010 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
12020 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
12030 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
12040 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
12050 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
12060 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12070 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
12080 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
12090 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
120a0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
120b0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
120c0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
120d0 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
120e0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
120f0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
12100 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12110 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12120 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12130 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12140 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12150 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12160 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
12170 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
12180 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
12190 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
121a0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
121b0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
121c0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
121d0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
121e0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
121f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
12200 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
12210 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12220 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
12230 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12240 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12250 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12260 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
12270 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12280 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
12290 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
122a0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
122b0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
122c0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
122d0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
122e0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
122f0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
12300 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
12310 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
12320 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
12330 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12340 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12350 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
12360 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
12370 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
12380 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
12390 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
123a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
123b0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
123c0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
123d0 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
123e0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
123f0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
12400 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
12410 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
12420 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
12430 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
12440 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
12450 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
12460 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
12470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12480 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
12490 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
124a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
124b0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
124c0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
124d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
124e0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
124f0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
12500 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
12510 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
12520 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
12530 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
12540 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12550 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12560 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
12570 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
12580 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
12590 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
125a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
125b0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
125c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
125d0 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
125e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
125f0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
12600 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
12610 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
12620 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
12630 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
12640 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
12650 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
12660 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
12670 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
12680 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
12690 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
126a0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
126b0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
126c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
126d0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
126e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
126f0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
12700 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
12710 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
12720 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
12730 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
12740 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12750 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
12760 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
12770 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
12780 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
12790 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
127a0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
127b0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
127c0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
127d0 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
127e0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
127f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12800 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
12810 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
12820 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
12830 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
12840 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
12850 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
12860 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12870 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
12880 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
12890 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
128a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
128b0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
128c0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
128d0 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
128e0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
128f0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
12900 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12910 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12920 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12930 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12940 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12950 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
12960 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
12970 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12990 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
129a0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
129b0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
129c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
129d0 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
129e0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
129f0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
12a00 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
12a10 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12a20 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12a30 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12a40 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
12a50 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
12a60 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
12a70 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
12a80 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12a90 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
12aa0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
12ab0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12ac0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
12ad0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
12ae0 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
12af0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
12b00 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
12b10 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
12b20 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12b30 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
12b40 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
12b50 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
12b60 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
12b70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12b80 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
12b90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12ba0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
12bb0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
12bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12bd0 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
12be0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
12bf0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
12c00 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
12c10 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12c20 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12c30 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12c40 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
12c50 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12c60 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
12c70 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
12c80 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
12c90 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
12ca0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
12cb0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
12cc0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
12cd0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
12ce0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
12cf0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
12d00 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
12d10 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
12d20 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
12d30 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
12d40 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
12d50 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
12d60 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
12d70 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12d80 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
12d90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12da0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
12db0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
12dc0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12dd0 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
12de0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
12df0 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
12e00 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
12e10 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
12e20 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
12e30 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
12e40 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
12e50 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12e60 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
12e70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
12e80 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
12e90 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
12ea0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
12eb0 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
12ec0 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
12ed0 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
12ee0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12ef0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
12f00 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12f10 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
12f20 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
12f30 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
12f40 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
12f50 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12f60 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
12f70 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
12f80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12f90 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
12fa0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
12fb0 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
12fc0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
12fd0 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
12fe0 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
12ff0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
13000 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
13010 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13020 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
13030 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
13040 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13050 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
13060 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13070 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
13080 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13090 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
130a0 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  CH option specif
130b0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
130c0 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  ory buffer.** th
130d0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
130e0 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65  e for scratch me
130f0 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61  mory.  ^(There a
13100 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
13110 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f  ts.** to SQLITE_
13120 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20  CONFIG_SCRATCH: 
13130 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
13140 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
13150 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
13160 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
13170 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
13180 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
13190 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
131a0 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
131b0 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
131c0 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
131d0 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
131e0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
131f0 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ).)^.** The firs
13200 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
13210 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
13220 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
13230 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
13240 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
13250 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
13260 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f   ^SQLite will no
13270 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20  t use more than 
13280 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
13290 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a  ers per thread..
132a0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
132b0 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20  never request a 
132c0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
132d0 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
132e0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
132f0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
13300 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  ze..** ^If SQLit
13310 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
13320 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
13330 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
13340 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
13350 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
13360 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
13370 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
13380 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
13390 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
133a0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
133b0 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68  eeded.<p>.** ^Wh
133c0 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  en the applicati
133d0 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20  on provides any 
133e0 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63  amount of scratc
133f0 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a  h memory using.*
13400 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
13410 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20  SCRATCH, SQLite 
13420 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61  avoids unnecessa
13430 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c  ry large.** [sql
13440 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70  ite3_malloc|heap
13450 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a   allocations]..*
13460 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20  * This can help 
13470 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72  [Robson proof|pr
13480 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  event memory all
13490 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  ocation failures
134a0 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a  ] due to heap.**
134b0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69   fragmentation i
134c0 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62  n low-memory emb
134d0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a  edded systems..*
134e0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
134f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13500 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
13510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13520 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
13530 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
13540 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
13550 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13560 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a   a memory pool.*
13570 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
13580 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61  n use for the da
13590 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
135a0 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
135b0 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  lt page.** cache
135c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
135d0 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
135e0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
135f0 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e  is a no-op if an
13600 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
13610 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
13620 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13630 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
13640 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
13650 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a  FIG_PCACHE2]..**
13660 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
13670 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
13680 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13690 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65  ECACHE: A pointe
136a0 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61  r to.** 8-byte a
136b0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70  ligned memory (p
136c0 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f  Mem), the size o
136d0 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63 68  f each page cach
136e0 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20  e line (sz),.** 
136f0 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
13700 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e  f cache lines (N
13710 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
13720 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
13730 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
13740 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
13750 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
13760 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
13770 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 20   512 and 65536) 
13780 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20  plus some extra 
13790 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a  bytes for each.*
137a0 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
137b0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65  ^The number of e
137c0 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 65  xtra bytes neede
137d0 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68 65  d by the page he
137e0 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64  ader.** can be d
137f0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
13800 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13810 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a  CACHE_HDRSZ]..**
13820 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
13830 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
13840 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
13850 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61  ** for the sz pa
13860 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61  rameter to be la
13870 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73  rger than necess
13880 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a  ary.  The pMem.*
13890 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
138a0 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
138b0 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f   pointer or a po
138c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
138d0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c  te.** aligned bl
138e0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66  ock of memory of
138f0 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
13900 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a  ytes, otherwise.
13910 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  ** subsequent be
13920 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
13930 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d  ned..** ^When pM
13940 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  em is not NULL, 
13950 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69  SQLite will stri
13960 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65  ve to use the me
13970 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a  mory provided.**
13980 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 65   to satisfy page
13990 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61   cache needs, fa
139a0 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73  lling back to [s
139b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
139c0 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61   if.** a page ca
139d0 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67  che line is larg
139e0 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73  er than sz bytes
139f0 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68   or if all of th
13a00 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a  e pMem buffer.**
13a10 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
13a20 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55  * ^If pMem is NU
13a30 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d  LL and N is non-
13a40 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20  zero, then each 
13a50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13a60 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69  ion.** does an i
13a70 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f  nitial bulk allo
13a80 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20  cation for page 
13a90 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  cache memory.** 
13aa0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
13ab0 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65  lloc()] sufficie
13ac0 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c  nt for N cache l
13ad0 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73  ines if N is pos
13ae0 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d  itive or.** of -
13af0 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20  1024*N bytes if 
13b00 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e  N is negative, .
13b10 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
13b20 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
13b30 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
13b40 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
13b50 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69 6e  ovided by the in
13b60 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74  itial.** allocat
13b70 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ion, then SQLite
13b80 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
13b90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61  3_malloc()] sepa
13ba0 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a  rately for each.
13bb0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61  ** additional ca
13bc0 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a  che line. </dd>.
13bd0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13be0 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74  ONFIG_HEAP]] <dt
13bf0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
13c00 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
13c10 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13c20 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
13c30 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
13c40 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
13c50 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65   .** that SQLite
13c60 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c   will use for al
13c70 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
13c80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13c90 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f  on needs.** beyo
13ca0 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
13cb0 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  d for by [SQLITE
13cc0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
13cd0 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
13ce0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
13cf0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  ]..** ^The SQLIT
13d00 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
13d10 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
13d20 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
13d30 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
13d40 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c  with either [SQL
13d50 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
13d60 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45  S3] or [SQLITE_E
13d70 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
13d80 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  nd returns.** [S
13d90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13da0 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73  invoked otherwis
13db0 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65  e..** ^There are
13dc0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
13dd0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
13de0 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d  G_HEAP:.** An 8-
13df0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
13e00 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
13e10 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
13e20 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
13e30 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
13e40 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
13e50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13e60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
13e70 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
13e80 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
13e90 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
13ea0 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
13eb0 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
13ec0 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
13ed0 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
13ee0 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
13ef0 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
13f00 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
13f10 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
13f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
13f30 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
13f40 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
13f50 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  r is not NULL th
13f60 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
13f70 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
13f80 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
13f90 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
13fa0 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
13fb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13fc0 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
13fd0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
13fe0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
13ff0 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
14000 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
14010 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
14020 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
14030 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
14040 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
14050 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14060 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
14070 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
14080 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
14090 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
140a0 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
140b0 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
140c0 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
140d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
140e0 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
140f0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
14100 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
14110 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14120 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69  ONFIG_MUTEX opti
14130 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14140 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14150 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
14160 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
14170 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14180 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
14190 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
141a0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
141b0 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ies alternative 
141c0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
141d0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
141e0 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20  sed.** in place 
141f0 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
14200 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
14210 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
14220 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
14230 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
14240 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14250 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
14260 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
14270 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
14280 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14290 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
142a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
142b0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
142c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
142d0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
142e0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
142f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14300 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14310 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14320 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14330 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
14340 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
14350 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14360 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
14370 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14380 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
14390 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
143a0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
143b0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
143c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
143d0 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
143e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
143f0 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
14400 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14410 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14420 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14430 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14440 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
14450 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
14460 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
14470 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14480 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
14490 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
144a0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
144b0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
144c0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
144d0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
144e0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
144f0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
14500 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
14510 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
14520 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
14530 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
14540 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
14550 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
14560 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
14570 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
14580 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
14590 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
145a0 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
145b0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
145c0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
145d0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
145e0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
145f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14600 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
14610 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
14620 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
14630 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
14640 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
14650 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
14660 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
14670 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
14680 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
14690 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
146a0 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
146b0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
146c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
146d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
146e0 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
146f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14700 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
14710 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14720 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
14730 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
14740 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
14750 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65  determine.** the
14760 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66   default size of
14770 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
14780 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62  y on each [datab
14790 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
147a0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
147b0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
147c0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
147d0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
147e0 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
147f0 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
14800 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
14810 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
14820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14830 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f  on.)^  ^(SQLITE_
14840 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14850 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e  .** sets the <i>
14860 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b  default</i> look
14870 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20  aside size. The 
14880 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
14890 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f  _LOOKASIDE].** o
148a0 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65  ption to [sqlite
148b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
148c0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
148d0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
148e0 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
148f0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
14900 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
14910 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14920 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14930 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
14940 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14950 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14960 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14970 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  G_PCACHE2 option
14980 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14990 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
149a0 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
149b0 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  to an [sqlite3_p
149c0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
149d0 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
149e0 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ject specifies.*
149f0 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  * the interface 
14a00 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
14a10 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14a20 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c  ation.)^.** ^SQL
14a30 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
14a40 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14a50 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14a60 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a  ] object.</dd>.*
14a70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14a80 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
14a90 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14aa0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
14ab0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14ac0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14ad0 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f  GETPCACHE2 optio
14ae0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14af0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
14b00 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
14b10 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  to an [sqlite3_p
14b20 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
14b30 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20  object.  SQLite 
14b40 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65  copies of.** the
14b50 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61   current page ca
14b60 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14b70 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a  on into that obj
14b80 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ect.)^ </dd>.**.
14b90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14ba0 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c  IG_LOG]] <dt>SQL
14bb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
14bc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20  dt>.** <dd> The 
14bd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14be0 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  G option is used
14bf0 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68   to configure th
14c00 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62  e SQLite.** glob
14c10 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a  al [error log]..
14c20 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f  ** (^The SQLITE_
14c30 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
14c40 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
14c50 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
14c60 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
14c70 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
14c80 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
14c90 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
14ca0 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
14cb0 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
14cc0 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
14cd0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
14ce0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
14cf0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
14d00 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14d10 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
14d20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
14d30 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
14d40 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
14d50 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
14d60 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
14d70 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
14d80 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
14d90 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
14da0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
14db0 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
14dc0 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
14dd0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
14de0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
14df0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
14e00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
14e10 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
14e20 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
14e30 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
14e40 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
14e50 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
14e60 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
14e70 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
14e80 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
14e90 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14ea0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
14eb0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
14ec0 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
14ed0 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
14ee0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
14ef0 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
14f00 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
14f10 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14f20 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
14f30 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
14f40 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
14f50 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
14f60 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
14f70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
14f80 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
14f90 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
14fa0 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
14fb0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
14fc0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
14fd0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
14fe0 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
14ff0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
15000 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
15010 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
15020 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
15030 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
15040 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
15050 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
15060 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
15070 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
15080 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
15090 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
150a0 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  d>^(The SQLITE_C
150b0 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e  ONFIG_URI option
150c0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
150d0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
150e0 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d   int..** If non-
150f0 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
15100 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
15110 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
15120 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
15130 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55   zero,.** then U
15140 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
15150 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
15160 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64  .)^ ^If URI hand
15170 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
15180 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c  .** enabled, all
15190 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65   filenames passe
151a0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
151b0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
151c0 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  open_v2()],.** [
151d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
151e0 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65  ] or.** specifie
151f0 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54  d as part of [AT
15200 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61  TACH] commands a
15210 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
15220 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65  s URIs, regardle
15230 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72  ss.** of whether
15240 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c   or not the [SQL
15250 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
15260 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
15270 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
15280 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
15290 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67  ned. ^If it is g
152a0 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
152b0 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
152c0 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
152d0 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
152e0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
152f0 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
15300 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
15310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
15320 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64  s opened. ^(By d
15330 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
15340 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
15350 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
15360 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
15370 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
15380 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
15390 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
153a0 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
153b0 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  defined.)^.**.**
153c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
153d0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
153e0 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SCAN]] <dt>SQLIT
153f0 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
15400 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20  G_INDEX_SCAN.** 
15410 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
15420 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
15430 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f  INDEX_SCAN optio
15440 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15450 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75   integer.** argu
15460 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e  ment which is in
15470 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
15480 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20  oolean in order 
15490 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
154a0 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20  able.** the use 
154b0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
154c0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
154d0 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20  le scans in the 
154e0 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e  query optimizer.
154f0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
15500 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65   setting is dete
15510 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
15520 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43   [SQLITE_ALLOW_C
15530 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
15540 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  AN] compile-time
15550 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22   option, or is "
15560 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63  on".** if that c
15570 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15580 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
15590 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f  * The ability to
155a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
155b0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
155c0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
155d0 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20  ble scans.** is 
155e0 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63  because some inc
155f0 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c  orrectly coded l
15600 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f  egacy applicatio
15610 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63  ns might malfunc
15620 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  tion.** when the
15630 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
15640 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
15650 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
15660 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
15670 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
15680 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
15690 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
156a0 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
156b0 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
156c0 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
156d0 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
156e0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
156f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15700 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
15710 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
15720 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15730 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
15740 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
15750 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
15760 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
15770 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
15780 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
15790 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
157a0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
157b0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
157c0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
157d0 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
157e0 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  -ops..** </dd>.*
157f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15800 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
15810 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15820 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
15830 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
15840 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15850 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
15860 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
15870 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
15880 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63  SQLLOG] pre-proc
15890 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
158a0 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
158b0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
158c0 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
158d0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
158e0 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
158f0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
15900 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
15910 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
15920 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
15930 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
15940 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
15950 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
15960 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
15970 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
15980 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
15990 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
159a0 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
159b0 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
159c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
159d0 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
159e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
159f0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
15a00 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
15a10 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
15a20 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
15a30 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
15a40 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
15a50 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
15a60 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
15a70 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
15a80 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
15a90 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
15aa0 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
15ab0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
15ac0 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
15ad0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
15ae0 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
15af0 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
15b00 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
15b10 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
15b20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
15b30 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
15b40 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15b50 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
15b60 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
15b70 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
15b80 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
15b90 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
15ba0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20    An example of 
15bb0 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f  using this.** co
15bc0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15bd0 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69  on can be seen i
15be0 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c  n the "test_sqll
15bf0 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c  og.c" source fil
15c00 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f  e in.** the cano
15c10 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75  nical SQLite sou
15c20 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a  rce tree.</dd>.*
15c30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15c40 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  NFIG_MMAP_SIZE]]
15c50 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15c60 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a  ONFIG_MMAP_SIZE.
15c70 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
15c80 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
15c90 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74  takes two 64-bit
15ca0 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65   integer (sqlite
15cb0 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a  3_int64) values.
15cc0 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20  ** that are the 
15cd0 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a  default mmap siz
15ce0 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66  e limit (the def
15cf0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72  ault setting for
15d00 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  .** [PRAGMA mmap
15d10 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20  _size]) and the 
15d20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
15d30 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e  mmap size limit.
15d40 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
15d50 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20   setting can be 
15d60 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61  overridden by ea
15d70 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
15d80 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  ection using.** 
15d90 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47  either the [PRAG
15da0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f  MA mmap_size] co
15db0 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69  mmand, or by usi
15dc0 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
15dd0 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
15de0 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e  E] file control.
15df0 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20    ^(The maximum 
15e00 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
15e10 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c  e.** will be sil
15e20 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
15e30 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20  if necessary so 
15e40 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
15e50 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63   exceed the.** c
15e60 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69  ompile-time maxi
15e70 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65  mum mmap size se
15e80 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
15e90 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a  ITE_MAX_MMAP_SIZ
15ea0 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
15eb0 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66  option.)^.** ^If
15ec0 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74   either argument
15ed0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20   to this option 
15ee0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
15ef0 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20  n that argument 
15f00 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f  is.** changed to
15f10 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   its compile-tim
15f20 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  e default..**.**
15f30 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15f40 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d  _WIN32_HEAPSIZE]
15f50 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15f60 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15f70 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PSIZE.** <dd>^Th
15f80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15f90 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f  WIN32_HEAPSIZE o
15fa0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
15fb0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
15fc0 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
15fd0 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74   for Windows wit
15fe0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49  h the [SQLITE_WI
15ff0 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d  N32_MALLOC] pre-
16000 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a  processor macro.
16010 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c  ** defined. ^SQL
16020 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16030 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20  _HEAPSIZE takes 
16040 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 32-bit unsigne
16050 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a  d integer value.
16060 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65  ** that specifie
16070 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  s the maximum si
16080 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65  ze of the create
16090 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  d heap..**.** [[
160a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
160b0 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20  ACHE_HDRSZ]].** 
160c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
160d0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a  G_PCACHE_HDRSZ.*
160e0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
160f0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
16100 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  HDRSZ option tak
16110 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
16120 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
16130 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16140 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72  n integer and wr
16150 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69  ites into that i
16160 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65  nteger the numbe
16170 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79  r of extra.** by
16180 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71  tes per page req
16190 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70  uired for each p
161a0 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43  age in [SQLITE_C
161b0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
161c0 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20  ..** The amount 
161d0 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72  of extra space r
161e0 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e  equired can chan
161f0 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ge depending on 
16200 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a  the compiler,.**
16210 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d   target platform
16220 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  , and SQLite ver
16230 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  sion..**.** [[SQ
16240 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
16250 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
16260 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a  E_CONFIG_PMASZ.*
16270 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
16280 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f  E_CONFIG_PMASZ o
16290 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
162a0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
162b0 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e  hich.** is an un
162c0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
162d0 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e  nd sets the "Min
162e0 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66  imum PMA Size" f
162f0 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65  or the multithre
16300 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74  aded.** sorter t
16310 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20  o that integer. 
16320 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e   The default min
16330 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73  imum PMA Size is
16340 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
16350 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d  SQLITE_SORTER_PM
16360 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ASZ] compile-tim
16370 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74  e option.  New t
16380 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63  hreads are launc
16390 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77  hed.** to help w
163a0 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69  ith sort operati
163b0 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68  ons when multith
163c0 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a  readed sorting.*
163d0 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73  * is enabled (us
163e0 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ing the [PRAGMA 
163f0 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64  threads] command
16400 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74  ) and the amount
16410 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74   of content.** t
16420 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65  o be sorted exce
16430 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a  eds the page siz
16440 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69  e times the mini
16450 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50  mum of the.** [P
16460 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65  RAGMA cache_size
16470 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68  ] setting and th
16480 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  is value..**.** 
16490 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
164a0 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d  STMTJRNL_SPILL]]
164b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
164c0 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
164d0 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  PILL.** <dd>^The
164e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
164f0 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70  TMTJRNL_SPILL op
16500 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16510 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
16520 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74  ich.** becomes t
16530 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f  he [statement jo
16540 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d  urnal] spill-to-
16550 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20  disk threshold. 
16560 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20   .** [Statement 
16570 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65  journals] are he
16580 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74  ld in memory unt
16590 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69  il their size (i
165a0 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65  n bytes).** exce
165b0 65 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f  eds this thresho
165c0 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69  ld, at which poi
165d0 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74  nt they are writ
165e0 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20  ten to disk..** 
165f0 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68  Or if the thresh
16600 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65  old is -1, state
16610 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72  ment journals ar
16620 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a  e always held.**
16630 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20   exclusively in 
16640 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65  memory..** Since
16650 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20   many statement 
16660 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62  journals never b
16670 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74  ecome large, set
16680 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a  ting the spill.*
16690 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61  * threshold to a
166a0 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36   value such as 6
166b0 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79  4KiB can greatly
166c0 20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75   reduce the amou
166d0 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71  nt of.** I/O req
166e0 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74  uired to support
166f0 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62   statement rollb
16700 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  ack..** The defa
16710 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
16720 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f  is setting is co
16730 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a  ntrolled by the.
16740 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a  ** [SQLITE_STMTJ
16750 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69  RNL_SPILL] compi
16760 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
16770 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
16780 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16790 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
167a0 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
167b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
167c0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
167d0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
167e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
167f0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
16800 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
16810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16820 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
16830 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
16840 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
16850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16860 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
16870 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
16880 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
16890 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
168a0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
168b0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
168c0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
168d0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
168e0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
168f0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
16900 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
16910 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
16920 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
16930 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
16940 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
16950 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
16960 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16970 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
16980 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
16990 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
169a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
169b0 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
169c0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
169d0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
169e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
169f0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
16a00 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
16a10 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
16a20 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
16a30 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
16a40 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
16a50 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
16a60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16a70 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
16a80 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
16a90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16aa0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
16ab0 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
16ac0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
16ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
16ae0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
16af0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
16b00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16b10 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
16b20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
16b30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16b40 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
16b50 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
16b60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16b70 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16b80 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
16b90 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
16ba0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
16bb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16bc0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
16bd0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
16be0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
16bf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16c00 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
16c10 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
16c20 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16c30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
16c40 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
16c50 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
16c60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16c70 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
16c80 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
16c90 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
16ca0 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
16cb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16cc0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16cd0 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
16ce0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
16cf0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16d00 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20  G_PCACHE_HDRSZ  
16d10 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74        24  /* int
16d20 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65   *psz */.#define
16d30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16d40 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20  MASZ            
16d50 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e     25  /* unsign
16d60 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a  ed int szPma */.
16d70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16d80 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
16d90 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a  PILL      26  /*
16da0 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f   int nByte */../
16db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
16dc0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
16dd0 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
16de0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
16df0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
16e00 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
16e10 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
16e20 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
16e30 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
16e40 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
16e50 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
16e60 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
16e70 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
16e80 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
16e90 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16ea0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
16eb0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
16ec0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
16ed0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
16ee0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
16ef0 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
16f00 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
16f10 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
16f20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
16f30 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
16f40 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
16f50 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
16f60 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
16f70 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
16f80 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16f90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
16fa0 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
16fb0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
16fc0 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
16fd0 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
16fe0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
16ff0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
17000 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
17010 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
17020 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
17030 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
17040 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
17050 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
17060 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
17070 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
17080 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
17090 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
170a0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
170b0 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
170c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
170d0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
170e0 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
170f0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
17100 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17110 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
17120 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
17130 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
17140 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
17150 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
17160 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
17170 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
17180 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17190 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
171a0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
171b0 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
171c0 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
171d0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
171e0 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
171f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
17200 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
17210 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
17220 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
17230 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
17240 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
17250 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
17260 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
17270 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
17280 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
17290 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
172a0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
172b0 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
172c0 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
172d0 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
172e0 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
172f0 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
17300 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
17310 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
17320 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
17330 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
17340 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
17350 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17360 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
17370 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
17380 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
17390 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
173a0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
173b0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
173c0 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
173d0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
173e0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
173f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17400 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
17410 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
17420 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
17430 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
17440 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
17450 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
17460 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
17470 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
17480 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
17490 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
174a0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
174b0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
174c0 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
174d0 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
174e0 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
174f0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
17500 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
17510 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
17520 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
17530 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
17540 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
17550 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
17560 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
17570 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
17580 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17590 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
175a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
175b0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
175c0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
175d0 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
175e0 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
175f0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
17600 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
17610 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
17620 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17630 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
17640 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
17650 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
17660 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
17670 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
17680 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17690 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
176a0 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
176b0 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
176c0 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
176d0 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
176e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
176f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17700 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17710 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
17720 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17730 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
17740 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
17750 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
17760 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
17770 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17780 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
17790 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
177a0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
177b0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
177c0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
177d0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
177e0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
177f0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
17800 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
17810 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
17820 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
17830 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
17840 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
17850 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
17860 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
17870 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
17880 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
17890 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
178a0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
178b0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
178c0 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
178d0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
178e0 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
178f0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
17900 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
17910 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
17920 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17930 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
17940 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
17950 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
17960 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
17970 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
17980 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
17990 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
179a0 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
179b0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
179c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
179d0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
179e0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
179f0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
17a00 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
17a10 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
17a20 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
17a30 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17a40 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
17a50 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a  TOKENIZER</dt>.*
17a60 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17a70 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
17a80 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
17a90 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e   the two-argumen
17aa0 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  t.** version of 
17ab0 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69  the [fts3_tokeni
17ac0 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  zer()] function 
17ad0 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66  which is part of
17ae0 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66   the.** [FTS3] f
17af0 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20  ull-text search 
17b00 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e  engine extension
17b10 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
17b20 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
17b30 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
17b40 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
17b50 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
17b60 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
17b70 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f   disable fts3_to
17b80 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20  kenizer() or.** 
17b90 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
17ba0 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  le fts3_tokenize
17bb0 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20  r() or negative 
17bc0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
17bd0 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ting.** unchange
17be0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
17bf0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17c00 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17c10 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17c20 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
17c30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17c40 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74  e whether fts3_t
17c50 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61  okenizer is disa
17c60 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
17c70 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
17c80 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
17c90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
17ca0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
17cb0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
17cc0 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65   case the new se
17cd0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
17ce0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
17cf0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
17d00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
17d10 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
17d20 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  N</dt>.** <dd> ^
17d30 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17d40 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
17d50 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71   disable the [sq
17d60 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
17d70 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  sion()].** inter
17d80 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74  face independent
17d90 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f  ly of the [load_
17da0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c  extension()] SQL
17db0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
17dc0 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  e [sqlite3_enabl
17dd0 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
17de0 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20  ()] API enables 
17df0 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68  or disables both
17e00 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73   the.** C-API [s
17e10 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
17e20 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65  nsion()] and the
17e30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c   SQL function [l
17e40 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
17e50 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
17e60 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
17e70 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
17e80 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74  * When the first
17e90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
17ea0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31  s interface is 1
17eb0 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20  , then only the 
17ec0 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62  C-API is.** enab
17ed0 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  led and the SQL 
17ee0 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73  function remains
17ef0 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74   disabled.  If t
17f00 68 65 20 66 69 72 73 74 20 61 72 67 6d 65 6e 74  he first argment
17f10 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65   to.** this inte
17f20 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e  rface is 0, then
17f30 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20   both the C-API 
17f40 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
17f50 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65  tion are disable
17f60 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  d..** If the fir
17f70 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d  st argument is -
17f80 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67  1, then no chang
17f90 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73  es are made to s
17fa0 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74  tate of either t
17fb0 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74  he.** C-API or t
17fc0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
17fd0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
17fe0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
17ff0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
18000 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
18010 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18020 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18030 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33  whether [sqlite3
18040 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18050 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
18060 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
18070 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67  nabled following
18080 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
18090 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
180a0 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55  r may.** be a NU
180b0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77  LL pointer, in w
180c0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
180d0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
180e0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a   reported back..
180f0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
18100 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
18110 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18120 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
18130 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f        1001 /* vo
18140 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
18150 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18160 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
18170 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30  EY           100
18180 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  2 /* int int* */
18190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
181a0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
181b0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31  TRIGGER        1
181c0 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  003 /* int int* 
181d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
181e0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
181f0 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
18200 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74   1004 /* int int
18210 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18220 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18230 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
18240 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69  ON 1005 /* int i
18250 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
18260 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
18270 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
18280 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
18290 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
182a0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
182b0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
182c0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
182d0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
182e0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
182f0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
18300 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
18310 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
18320 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
18330 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
18340 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
18350 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
18360 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
18370 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18380 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
18390 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
183a0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
183b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
183c0 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
183d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
183e0 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  3.**.** ^Each en
183f0 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69  try in most SQLi
18400 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70  te tables (excep
18410 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52  t for [WITHOUT R
18420 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a  OWID] tables).**
18430 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
18440 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
18450 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
18460 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
18470 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
18480 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
18490 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
184a0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
184b0 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
184c0 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
184d0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
184e0 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
184f0 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
18500 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
18510 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
18520 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
18530 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
18540 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
18550 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
18560 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
18570 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
18580 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
18590 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
185a0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
185b0 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (D) interface re
185c0 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
185d0 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73  ] of the .** mos
185e0 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
185f0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
18600 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
18610 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
18620 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
18630 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
18640 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f  ** ^Inserts into
18650 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
18660 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20   tables are not 
18670 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66  recorded..** ^If
18680 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
18690 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f  INSERT]s into ro
186a0 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61  wid tables.** ha
186b0 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
186c0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
186d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a   connection D, .
186e0 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
186f0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
18700 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72  d(D) returns zer
18710 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  o..**.** ^(If an
18720 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
18730 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
18740 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
18750 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
18760 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
18770 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
18780 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
18790 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
187a0 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
187b0 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
187c0 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
187d0 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
187e0 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
187f0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
18800 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
18810 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
18820 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
18830 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
18840 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
18850 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
18860 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
18870 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
18880 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
18890 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
188a0 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
188b0 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
188c0 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
188d0 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
188e0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
188f0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
18900 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18910 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
18920 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
18930 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
18940 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
18950 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
18960 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
18970 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
18980 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
18990 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
189a0 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
189b0 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
189c0 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
189d0 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
189e0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
189f0 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
18a00 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
18a10 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
18a20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
18a30 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
18a40 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
18a50 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
18a60 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
18a70 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
18a80 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
18a90 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
18aa0 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
18ab0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
18ac0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
18ad0 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
18ae0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
18af0 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
18b00 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
18b10 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
18b20 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
18b30 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
18b40 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
18b50 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
18b60 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
18b70 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
18b80 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
18b90 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
18ba0 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
18bb0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
18bc0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
18bd0 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
18be0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
18bf0 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
18c00 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
18c10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
18c20 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
18c30 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
18c40 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
18c50 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
18c60 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
18c70 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
18c80 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
18c90 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
18ca0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
18cb0 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
18cc0 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
18cd0 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
18ce0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
18cf0 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
18d00 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
18d10 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
18d20 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
18d30 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
18d40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18d50 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
18d60 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
18d70 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
18d80 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
18d90 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18da0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
18db0 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69  rows modified, i
18dc0 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65  nserted or.** de
18dd0 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
18de0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
18df0 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
18e00 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  ATE or DELETE.**
18e10 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
18e20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18e30 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
18e40 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  by the only para
18e50 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75  meter..** ^Execu
18e60 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
18e70 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
18e80 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f  ment does not mo
18e90 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a  dify the value.*
18ea0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  * returned by th
18eb0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
18ec0 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ** ^Only changes
18ed0 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62   made directly b
18ee0 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
18ef0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
18f00 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20  tatement are.** 
18f10 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78  considered - aux
18f20 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
18f30 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45  aused by [CREATE
18f40 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
18f50 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69  ers], .** [forei
18f60 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
18f70 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  or [REPLACE] con
18f80 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
18f90 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  on are not count
18fa0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67  ed..** .** Chang
18fb0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
18fc0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
18fd0 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41  d by .** [INSTEA
18fe0 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49  D OF trigger | I
18ff0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
19000 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  rs] are not coun
19010 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20  ted. ^The value 
19020 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
19030 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19040 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  ) immediately af
19050 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55  ter an INSERT, U
19060 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c  PDATE or .** DEL
19070 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75  ETE statement ru
19080 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61  n on a view is a
19090 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79  lways zero. Only
190a0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f   changes made to
190b0 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73   real .** tables
190c0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
190d0 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d  .** Things are m
190e0 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20  ore complicated 
190f0 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  if the sqlite3_c
19100 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
19110 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64  n is.** executed
19120 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72   while a trigger
19130 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e   program is runn
19140 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61  ing. This may ha
19150 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70  ppen if the.** p
19160 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20  rogram uses the 
19170 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
19180 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20  unction], or if 
19190 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62  some other callb
191a0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
191b0 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f  invokes sqlite3_
191c0 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74  changes() direct
191d0 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a  ly. Essentially:
191e0 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  .** .** <ul>.** 
191f0 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20    <li> ^(Before 
19200 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67  entering a trigg
19210 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76  er program the v
19220 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
19230 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74  .**        sqlit
19240 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
19250 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20  ction is saved. 
19260 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65  After the trigge
19270 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20  r program .**   
19280 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65       has finishe
19290 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  d, the original 
192a0 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65  value is restore
192b0 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c  d.)^.** .**   <l
192c0 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72  i> ^(Within a tr
192d0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61  igger program ea
192e0 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ch INSERT, UPDAT
192f0 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a  E and DELETE .**
19300 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
19310 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65  t sets the value
19320 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
19330 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
19340 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63  **        upon c
19350 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72  ompletion as nor
19360 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20  mal. Of course, 
19370 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20  this value will 
19380 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20  not include .** 
19390 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67         any chang
193a0 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  es performed by 
193b0 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73  sub-triggers, as
193c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
193d0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
193e0 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20    value will be 
193f0 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72  saved and restor
19400 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75  ed after each su
19410 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75  b-trigger has ru
19420 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  n.)^.** </ul>.**
19430 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73   .** ^This means
19440 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61   that if the cha
19450 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
19460 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29  ion (or similar)
19470 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74   is used.** by t
19480 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c  he first INSERT,
19490 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
194a0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
194b0 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74  in a trigger, it
194c0 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65   .** returns the
194d0 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68   value as set wh
194e0 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73  en the calling s
194f0 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65  tatement began e
19500 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66  xecuting..** ^If
19510 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74   it is used by t
19520 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62  he second or sub
19530 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61  sequent such sta
19540 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
19550 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67  trigger .** prog
19560 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72  ram, the value r
19570 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73  eturned reflects
19580 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
19590 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20  ows modified by 
195a0 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73  the .** previous
195b0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
195c0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
195d0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
195e0 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a  ame trigger..**.
195f0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
19600 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
19610 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
19620 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
19630 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
19640 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
19650 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
19660 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
19670 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
19680 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
19690 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
196a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
196b0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
196c0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
196d0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
196e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
196f0 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
19700 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
19710 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
19720 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
19730 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19740 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
19750 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
19760 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
19770 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19780 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
19790 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
197a0 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  l number of rows
197b0 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66   inserted, modif
197c0 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ied or.** delete
197d0 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54  d by all [INSERT
197e0 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ], [UPDATE] or [
197f0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
19800 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20  ts completed.** 
19810 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
19820 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61  se connection wa
19830 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64  s opened, includ
19840 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74  ing those execut
19850 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
19860 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19870 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  s. ^Executing an
19880 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
19890 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
198a0 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74   does not affect
198b0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
198c0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
198d0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a  otal_changes()..
198e0 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  ** .** ^Changes 
198f0 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
19900 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
19910 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64  ions] are includ
19920 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75  ed in the.** cou
19930 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61  nt, but those ma
19940 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45  de as part of RE
19950 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
19960 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a   resolution are.
19970 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73  ** not. ^Changes
19980 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
19990 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
199a0 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  by INSTEAD OF tr
199b0 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e  iggers .** are n
199c0 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
199d0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
199e0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
199f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
19a00 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
19a10 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
19a20 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
19a30 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
19a40 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
19a50 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
19a60 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
19a70 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
19a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
19a90 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
19aa0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
19ab0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
19ac0 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
19ad0 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
19ae0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
19af0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
19b00 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
19b10 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
19b20 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
19b30 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
19b40 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
19b50 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  uery.** METHOD: 
19b60 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
19b70 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
19b80 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
19b90 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
19ba0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
19bb0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
19bc0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
19bd0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
19be0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
19bf0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
19c00 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
19c10 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
19c20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
19c30 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
19c40 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
19c50 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
19c60 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
19c70 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
19c80 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
19c90 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
19ca0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
19cb0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
19cc0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
19cd0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
19ce0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
19cf0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
19d00 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
19d10 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
19d20 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
19d30 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
19d40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19d50 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
19d60 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
19d70 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
19d80 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
19d90 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
19da0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
19db0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
19dc0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
19dd0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
19de0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
19df0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
19e00 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
19e10 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
19e20 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
19e30 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
19e40 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
19e50 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
19e60 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
19e70 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
19e80 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
19e90 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
19ea0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
19eb0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
19ec0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
19ed0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
19ee0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
19ef0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
19f00 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
19f10 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
19f20 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
19f30 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
19f40 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
19f50 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
19f60 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
19f70 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
19f80 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
19f90 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
19fa0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
19fb0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
19fc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
19fd0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
19fe0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
19ff0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1a000 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1a010 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1a020 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
1a030 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
1a040 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
1a050 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1a060 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
1a070 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
1a080 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
1a090 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
1a0a0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1a0b0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
1a0c0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1a0d0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1a0e0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
1a0f0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
1a100 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
1a110 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
1a120 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
1a130 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
1a140 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
1a150 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
1a160 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
1a170 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
1a180 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1a190 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
1a1a0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
1a1b0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
1a1c0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1a1d0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1a1e0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1a1f0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
1a200 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
1a210 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a220 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
1a230 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
1a240 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
1a250 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
1a260 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
1a270 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
1a280 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1a290 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1a2a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a2b0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1a2c0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1a2d0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1a2e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1a2f0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1a300 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1a310 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1a320 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1a330 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1a340 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1a350 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1a360 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1a370 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1a380 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1a390 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1a3a0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1a3b0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1a3c0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1a3d0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1a3e0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1a3f0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1a400 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1a410 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1a420 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1a430 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1a440 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1a450 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1a460 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1a470 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1a480 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1a490 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1a4a0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1a4b0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1a4c0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1a4d0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1a4e0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1a4f0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1a500 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1a510 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1a520 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1a530 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1a540 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1a550 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1a560 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1a570 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1a580 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1a590 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1a5a0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1a5b0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1a5c0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1a5d0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1a5e0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1a5f0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1a600 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1a610 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1a620 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1a630 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1a640 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1a650 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1a660 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1a670 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1a680 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1a690 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1a6a0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1a6b0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1a6c0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1a6d0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1a6e0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1a6f0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1a700 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1a710 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1a720 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1a730 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1a740 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1a750 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1a760 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1a770 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1a780 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1a790 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1a7a0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1a7b0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1a7c0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1a7d0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1a7e0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1a7f0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1a800 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1a810 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1a820 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1a830 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1a840 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1a850 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1a860 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1a870 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1a880 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1a890 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1a8a0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1a8b0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1a8c0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1a8d0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1a8e0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
1a8f0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1a900 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1a910 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
1a920 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1a930 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1a940 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1a950 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1a960 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1a970 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1a980 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1a990 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1a9a0 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1a9b0 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1a9c0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1a9d0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1a9e0 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1a9f0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1aa00 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1aa10 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1aa20 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1aa30 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1aa40 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1aa50 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1aa60 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1aa70 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1aa80 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1aa90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1aaa0 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1aab0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1aac0 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1aad0 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1aae0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1aaf0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1ab00 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1ab10 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1ab20 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1ab30 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1ab40 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1ab50 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1ab60 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1ab70 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1ab80 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1ab90 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1aba0 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1abb0 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1abc0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1abd0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1abe0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1abf0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1ac00 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1ac10 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1ac20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1ac30 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1ac40 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1ac50 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1ac60 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1ac70 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1ac80 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1ac90 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1aca0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1acb0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1acc0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1acd0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1ace0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1acf0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1ad00 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1ad10 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1ad20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1ad30 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1ad40 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1ad50 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1ad60 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1ad70 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1ad80 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1ad90 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1ada0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1adb0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1adc0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1add0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1ade0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1adf0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1ae00 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1ae10 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1ae20 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1ae30 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1ae40 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1ae50 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1ae60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1ae70 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1ae80 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1ae90 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1aea0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1aeb0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1aec0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1aed0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1aee0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1aef0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1af00 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1af10 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1af20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1af30 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1af40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1af50 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1af60 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1af70 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1af80 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1af90 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1afa0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1afb0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1afc0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1afd0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1afe0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1aff0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1b000 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1b010 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1b020 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1b030 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1b040 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1b050 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1b060 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1b070 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1b080 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1b090 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1b0a0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1b0b0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1b0c0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1b0d0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1b0e0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1b0f0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1b100 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1b110 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1b120 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1b130 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1b140 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1b150 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1b160 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1b170 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1b180 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1b190 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1b1a0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1b1b0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1b1c0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1b1d0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1b1e0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1b1f0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1b200 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1b210 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1b220 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1b230 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1b240 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1b250 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1b260 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1b270 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1b280 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1b290 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1b2a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1b2b0 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1b2c0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1b2d0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1b2e0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1b2f0 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1b300 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1b310 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1b320 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1b330 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1b340 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1b350 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1b360 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1b370 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1b380 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1b390 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1b3a0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1b3b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b3c0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1b3d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1b3e0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1b3f0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1b400 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1b410 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1b420 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1b430 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1b440 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1b450 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1b460 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1b470 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b480 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1b490 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1b4a0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1b4b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1b4c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1b4d0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1b4e0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
1b4f0 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
1b500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b510 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1b520 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eout.** METHOD: 
1b530 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1b540 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1b550 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1b560 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1b570 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1b580 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1b590 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1b5a0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1b5b0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1b5c0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1b5d0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1b5e0 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1b5f0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1b600 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1b610 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1b620 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1b630 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1b640 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1b650 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1b660 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1b670 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1b680 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1b690 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1b6a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
1b6b0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
1b6c0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1b6d0 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
1b6e0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
1b6f0 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
1b700 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
1b710 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
1b720 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1b730 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1b740 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
1b750 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1b760 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b770 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
1b780 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
1b790 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
1b7a0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
1b7b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
1b7c0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
1b7d0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1b7e0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
1b7f0 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
1b800 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
1b810 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
1b820 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
1b830 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
1b840 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1b850 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
1b860 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
1b870 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1b880 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
1b890 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
1b8a0 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f  Queries.** METHO
1b8b0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1b8c0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1b8d0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1b8e0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1b8f0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1b900 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1b910 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1b920 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1b930 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1b940 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1b950 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1b960 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1b970 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1b980 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1b990 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1b9a0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1b9b0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1b9c0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1b9d0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1b9e0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1b9f0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1ba00 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1ba10 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1ba20 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1ba30 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1ba40 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1ba50 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1ba60 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1ba70 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1ba80 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1ba90 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1baa0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1bab0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1bac0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1bad0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1bae0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1baf0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1bb00 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1bb10 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1bb20 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1bb30 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1bb40 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1bb50 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1bb60 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1bb70 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1bb80 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1bb90 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1bba0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1bbb0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1bbc0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1bbd0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1bbe0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1bbf0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1bc00 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1bc10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1bc20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1bc30 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1bc40 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1bc50 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1bc60 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1bc70 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1bc80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1bc90 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1bca0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1bcb0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1bcc0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1bcd0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1bce0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1bcf0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1bd00 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1bd10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1bd20 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1bd30 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1bd40 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1bd50 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1bd60 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1bd70 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1bd80 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1bd90 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1bda0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1bdb0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1bdc0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1bdd0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1bde0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1bdf0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1be00 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1be10 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1be20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1be30 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1be40 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1be50 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1be60 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1be70 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1be80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1be90 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1bea0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1beb0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1bec0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1bed0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1bee0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1bef0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1bf00 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1bf10 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1bf20 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1bf30 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1bf40 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1bf50 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1bf60 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1bf70 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1bf80 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1bf90 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1bfa0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1bfb0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1bfc0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1bfd0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1bfe0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1bff0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1c000 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1c010 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c020 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1c030 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1c040 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1c050 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1c060 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1c070 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1c080 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c090 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1c0a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c0b0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1c0c0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1c0d0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1c0e0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1c0f0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1c100 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1c110 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1c120 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1c130 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1c140 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1c150 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1c160 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1c170 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1c180 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1c190 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1c1a0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1c1b0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1c1c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1c1d0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1c1e0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1c1f0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1c200 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1c210 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1c220 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1c230 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1c240 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1c250 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1c260 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1c270 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1c280 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1c290 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1c2a0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1c2b0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1c2c0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1c2d0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1c2e0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1c2f0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1c300 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1c310 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1c320 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1c330 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1c340 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1c350 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1c360 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1c370 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1c380 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1c390 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1c3a0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1c3b0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1c3c0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1c3d0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1c3e0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1c3f0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1c400 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1c410 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1c420 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1c430 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1c440 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1c450 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1c460 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1c470 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1c480 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1c490 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1c4a0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1c4b0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1c4c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1c4d0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1c4e0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1c4f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1c500 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1c510 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1c520 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1c530 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1c540 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1c550 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1c560 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1c570 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1c580 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1c590 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1c5a0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1c5b0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1c5c0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1c5d0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1c5e0 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1c5f0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1c600 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1c610 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1c620 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1c630 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1c640 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1c650 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1c660 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1c670 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1c680 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1c690 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1c6a0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1c6b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1c6c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1c6d0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1c6e0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1c6f0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1c700 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1c710 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1c720 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ry..** These rou
1c730 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64  tines understand
1c740 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d   most of the com
1c750 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69  mon K&R formatti
1c760 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70  ng options,.** p
1c770 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  lus some additio
1c780 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64  nal non-standard
1c790 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c   formats, detail
1c7a0 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74  ed below..** Not
1c7b0 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74  e that some of t
1c7c0 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20  he more obscure 
1c7d0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1c7e0 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a  ns from recent.*
1c7f0 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e  * C-library stan
1c800 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65  dards are omitte
1c810 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c  d from this impl
1c820 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ementation..**.*
1c830 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1c840 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1c850 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1c860 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1c870 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1c880 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1c890 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1c8a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
1c8b0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1c8c0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
1c8d0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
1c8e0 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
1c8f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
1c900 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
1c910 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
1c920 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1c930 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
1c940 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
1c950 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1c960 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1c970 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1c980 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1c990 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1c9a0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1c9b0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1c9c0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1c9d0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1c9e0 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1c9f0 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1ca00 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1ca10 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1ca20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1ca30 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1ca40 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1ca50 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1ca60 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1ca70 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1ca80 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1ca90 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1caa0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1cab0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1cac0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1cad0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1cae0 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1caf0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1cb00 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1cb10 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1cb20 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1cb30 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1cb40 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1cb50 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1cb60 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1cb70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1cb80 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1cb90 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1cba0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1cbb0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1cbc0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1cbd0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1cbe0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1cbf0 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1cc00 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1cc10 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1cc20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1cc30 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1cc40 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1cc50 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1cc60 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1cc70 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1cc80 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1cc90 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1cca0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1ccb0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1ccc0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1ccd0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1cce0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1ccf0 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1cd00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1cd10 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1cd20 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1cd30 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1cd40 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1cd50 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1cd60 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1cd70 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1cd80 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1cd90 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1cda0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
1cdb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cdc0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
1cdd0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
1cde0 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
1cdf0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1ce00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1ce10 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
1ce20 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
1ce30 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
1ce40 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
1ce50 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
1ce60 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
1ce70 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
1ce80 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
1ce90 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
1cea0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
1ceb0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
1cec0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
1ced0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77   "%q", "%Q", "%w
1cee0 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  " and "%z" optio
1cef0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1cf00 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1cf10 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1cf20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1cf30 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1cf40 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1cf50 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1cf60 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1cf70 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1cf80 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1cf90 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1cfa0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1cfb0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1cfc0 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1cfd0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1cfe0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1cff0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1d000 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1d010 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1d020 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1d030 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1d040 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1d050 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1d060 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1d070 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1d080 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1d090 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1d0a0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1d0b0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1d0c0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1d0d0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1d0e0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1d0f0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1d100 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1d110 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d120 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1d130 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1d140 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1d150 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1d160 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1d170 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1d180 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1d190 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1d1a0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1d1b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1d1c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1d1d0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1d1e0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1d1f0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1d200 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1d210 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1d220 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
1d230 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
1d240 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1d250 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1d260 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1d270 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
1d280 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
1d290 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1d2a0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1d2b0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
1d2c0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
1d2d0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
1d2e0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
1d2f0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
1d300 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
1d310 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1d320 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1d330 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1d340 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
1d350 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
1d360 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1d370 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
1d380 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
1d390 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
1d3a0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
1d3b0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
1d3c0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
1d3d0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
1d3e0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
1d3f0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
1d400 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
1d410 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
1d420 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
1d430 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
1d440 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
1d450 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
1d460 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
1d470 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
1d480 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
1d490 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
1d4a0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
1d4b0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
1d4c0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
1d4d0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
1d4e0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
1d4f0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
1d500 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
1d510 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
1d520 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
1d530 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1d540 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1d550 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1d560 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1d570 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
1d580 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1d590 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1d5a0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1d5b0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1d5c0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1d5d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1d5e0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
1d5f0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
1d600 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
1d610 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
1d620 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
1d630 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
1d640 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
1d650 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1d660 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74  (The "%w" format
1d670 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c  ting option is l
1d680 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20  ike "%q" except 
1d690 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20  that it expects 
1d6a0 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e  to.** be contain
1d6b0 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65  ed within double
1d6c0 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20  -quotes instead 
1d6d0 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  of single quotes
1d6e0 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61  , and it.** esca
1d6f0 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71  pes the double-q
1d700 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69  uote character i
1d710 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69  nstead of the si
1d720 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68  ngle-quote.** ch
1d730 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20  aracter.)^  The 
1d740 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1d750 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64  option is intend
1d760 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e  ed for safely in
1d770 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65  serting.** table
1d780 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   and column name
1d790 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75  s into a constru
1d7a0 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  cted SQL stateme
1d7b0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  nt..**.** ^(The 
1d7c0 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
1d7d0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1d7e0 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
1d7f0 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
1d800 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
1d810 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
1d820 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
1d830 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
1d840 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
1d850 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
1d860 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1d870 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  g.)^.*/.char *sq
1d880 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1d890 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1d8a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1d8b0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1d8c0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
1d8d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1d8e0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1d8f0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1d900 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1d910 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1d920 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1d930 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1d940 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1d950 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1d960 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1d970 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1d980 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1d990 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1d9a0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1d9b0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1d9c0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1d9d0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1d9e0 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1d9f0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1da00 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1da10 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1da20 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1da30 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1da40 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1da50 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1da60 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1da70 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1da80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1da90 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1daa0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1dab0 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1dac0 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1dad0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1dae0 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1daf0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1db00 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1db10 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1db20 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1db30 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1db40 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1db50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1db60 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1db70 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1db80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1db90 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1dba0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1dbb0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1dbc0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1dbd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1dbe0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29  ite3_malloc64(N)
1dbf0 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a   routine works j
1dc00 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69  ust like.** sqli
1dc10 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78  te3_malloc(N) ex
1dc20 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61  cept that N is a
1dc30 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69  n unsigned 64-bi
1dc40 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  t integer instea
1dc50 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64  d.** of a signed
1dc60 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e   32-bit integer.
1dc70 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1dc80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
1dc90 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
1dca0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
1dcb0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1dcc0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1dcd0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1dce0 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
1dcf0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
1dd00 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
1dd10 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1dd20 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
1dd30 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
1dd40 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1dd50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1dd60 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
1dd70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
1dd80 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
1dd90 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
1dda0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
1ddb0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
1ddc0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
1ddd0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
1dde0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
1ddf0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
1de00 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
1de10 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
1de20 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
1de30 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
1de40 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
1de50 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
1de60 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
1de70 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1de80 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
1de90 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
1dea0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
1deb0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
1dec0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
1ded0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
1dee0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1def0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1df00 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
1df10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1df20 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72  alloc(X,N) inter
1df30 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1df40 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1df50 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1df60 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20  tion X to be at 
1df70 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a  least N bytes..*
1df80 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61  * ^If the X para
1df90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1dfa0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a  _realloc(X,N).**
1dfb0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1dfc0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1dfd0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1dfe0 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1dff0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1e000 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20  )..** ^If the N 
1e010 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1e020 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1e030 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1e040 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1e050 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1e060 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1e070 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1e080 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a  ite3_free(X)..**
1e090 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1e0a0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61  c(X,N) returns a
1e0b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1e0c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1e0d0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1e0e0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1e0f0 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66  r NULL if insuff
1e100 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1e110 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e   available..** ^
1e120 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1e130 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1e140 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1e150 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1e160 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1e170 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1e180 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1e190 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1e1a0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1e1b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e1c0 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69  X,N) and the pri
1e1d0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1e1e0 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
1e1f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1e200 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,N) returns NULL
1e210 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69   and N is positi
1e220 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  ve, then the.** 
1e230 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1e240 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1e250 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e260 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29  3_realloc64(X,N)
1e270 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b   interfaces work
1e280 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a  s the same as.**
1e290 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1e2a0 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61  (X,N) except tha
1e2b0 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20  t N is a 64-bit 
1e2c0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
1e2d0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1e2e0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
1e2f0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nteger..**.** ^I
1e300 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20  f X is a memory 
1e310 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69  allocation previ
1e320 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
1e330 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1e340 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1e350 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c  _malloc64(), sql
1e360 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20  ite3_realloc(), 
1e370 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1e380 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20  oc64(), then.** 
1e390 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1e3a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
1e3b0 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79  e of that memory
1e3c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62   allocation in b
1e3d0 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61  ytes..** ^The va
1e3e0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1e3f0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1e400 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
1e410 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72   than the number
1e420 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71  .** of bytes req
1e430 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61  uested when X wa
1e440 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49  s allocated.  ^I
1e450 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f X is a NULL po
1e460 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71  inter then.** sq
1e470 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1e480 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66  eturns zero.  If
1e490 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d   X points to som
1e4a0 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e  ething that is n
1e4b0 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e  ot.** the beginn
1e4c0 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ing of memory al
1e4d0 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20  location, or if 
1e4e0 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66  it points to a f
1e4f0 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64  ormerly.** valid
1e500 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1e510 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20  on that has now 
1e520 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e  been freed, then
1e530 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
1e540 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   of sqlite3_msiz
1e550 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65  e(X) is undefine
1e560 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68  d and possibly h
1e570 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  armful..**.** ^T
1e580 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1e590 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1e5a0 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f  lloc(), sqlite3_
1e5b0 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  realloc(),.** sq
1e5c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1e5d0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
1e5e0 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20  alloc64().** is 
1e5f0 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
1e600 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
1e610 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
1e620 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
1e630 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
1e640 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
1e650 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
1e660 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
1e670 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
1e680 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
1e690 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
1e6a0 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
1e6b0 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
1e6c0 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
1e6d0 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
1e6e0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
1e6f0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
1e700 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
1e710 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
1e720 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
1e730 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
1e740 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
1e750 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
1e760 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
1e770 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1e780 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
1e790 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
1e7a0 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
1e7b0 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
1e7c0 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
1e7d0 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
1e7e0 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
1e7f0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1e800 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
1e810 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
1e820 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
1e830 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1e840 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
1e850 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
1e860 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
1e870 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
1e880 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
1e890 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
1e8a0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
1e8b0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
1e8c0 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
1e8d0 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
1e8e0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
1e8f0 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
1e900 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
1e910 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
1e920 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
1e930 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
1e940 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
1e950 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1e960 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1e970 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
1e980 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
1e990 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
1e9a0 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
1e9b0 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
1e9c0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1e9d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
1e9e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1e9f0 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
1ea00 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
1ea10 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
1ea20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
1ea30 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
1ea40 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
1ea50 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
1ea60 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
1ea70 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
1ea80 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1ea90 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
1eaa0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1eab0 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
1eac0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1ead0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1eae0 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
1eaf0 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a  _uint64);.void *
1eb00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1eb10 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
1eb20 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1eb30 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69  oc64(void*, sqli
1eb40 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1eb50 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
1eb60 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75  oid*);.sqlite3_u
1eb70 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73  int64 sqlite3_ms
1eb80 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ize(void*);../*.
1eb90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1eba0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1ebb0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1ebc0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1ebd0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1ebe0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1ebf0 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1ec00 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1ec10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1ec20 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1ec30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1ec40 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1ec50 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1ec60 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1ec70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1ec80 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1ec90 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1eca0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1ecb0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1ecc0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1ecd0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1ece0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1ecf0 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1ed00 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1ed10 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1ed20 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1ed30 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1ed40 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1ed50 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1ed60 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1ed70 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1ed80 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1ed90 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1eda0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1edb0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1edc0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1edd0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1ede0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1edf0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1ee00 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1ee10 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1ee20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1ee30 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1ee40 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1ee50 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1ee60 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1ee70 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1ee80 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1ee90 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1eea0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1eeb0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1eec0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1eed0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1eee0 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1eef0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1ef00 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1ef10 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1ef20 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1ef30 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1ef40 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1ef50 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1ef60 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1ef70 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1ef80 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1ef90 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1efa0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1efb0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1efc0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
1efd0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1efe0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
1eff0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1f000 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f010 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1f020 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1f030 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1f040 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1f050 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1f060 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1f070 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1f080 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1f090 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1f0a0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1f0b0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1f0c0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1f0d0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1f0e0 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1f0f0 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1f100 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1f110 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1f120 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1f130 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1f140 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1f150 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1f160 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1f170 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1f180 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1f190 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1f1a0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1f1b0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1f1c0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1f1d0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1f1e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1f1f0 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1f200 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1f210 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65  uffer P..** ^The
1f220 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e   P parameter can
1f230 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
1f240 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
1f250 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e  is routine has n
1f260 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73  ot been previous
1f270 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20  ly called or if 
1f280 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20  the previous.** 
1f290 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20  call had N less 
1f2a0 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55  than one or a NU
1f2b0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50  LL pointer for P
1f2c0 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20  , then the PRNG 
1f2d0 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69  is.** seeded usi
1f2e0 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
1f2f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  tained from the 
1f300 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
1f310 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66  od of.** the def
1f320 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1f330 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49  s] object..** ^I
1f340 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
1f350 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1f360 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20  ine had an N of 
1f370 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a  1 or more and a.
1f380 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68  ** non-NULL P th
1f390 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  en the pseudo-ra
1f3a0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
1f3b0 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
1f3c0 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
1f3d0 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
1f3e0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
1f3f0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
1f400 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
1f410 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1f420 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1f430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f440 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1f450 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1f460 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
1f470 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1f480 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1f490 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1f4a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1f4b0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1f4c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1f4d0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1f4e0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1f4f0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1f500 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f510 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1f520 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1f530 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1f540 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1f550 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1f560 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1f570 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f580 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1f590 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1f5a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1f5b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1f5c0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1f5d0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1f5e0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1f5f0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1f600 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1f610 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1f620 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1f630 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1f640 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1f650 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1f660 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1f670 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1f680 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f690 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1f6a0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1f6b0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1f6c0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1f6d0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1f6e0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1f6f0 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1f700 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1f710 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1f720 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1f730 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1f740 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1f750 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1f760 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1f770 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1f780 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1f790 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f7a0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1f7b0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1f7c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1f7d0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1f7e0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1f7f0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1f800 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f810 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1f820 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1f830 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1f840 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1f850 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1f860 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1f870 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1f880 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1f890 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1f8a0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1f8b0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1f8c0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1f8d0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1f8e0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1f8f0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1f900 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f910 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1f920 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1f930 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1f940 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1f950 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1f960 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1f970 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1f980 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1f990 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1f9a0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1f9b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f9c0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1f9d0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1f9e0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1f9f0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1fa00 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1fa10 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1fa20 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1fa30 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1fa40 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1fa50 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1fa60 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1fa70 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1fa80 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1fa90 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1faa0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1fab0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1fac0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1fad0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1fae0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1faf0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1fb00 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1fb10 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1fb20 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1fb30 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1fb40 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1fb50 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1fb60 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1fb70 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1fb80 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1fb90 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1fba0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1fbb0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1fbc0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1fbd0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1fbe0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1fbf0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1fc00 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1fc10 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1fc20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1fc30 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1fc40 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1fc50 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1fc60 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1fc70 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1fc80 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1fc90 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1fca0 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1fcb0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1fcc0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1fcd0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1fce0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1fcf0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1fd00 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1fd10 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1fd20 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1fd30 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1fd40 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1fd50 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1fd60 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1fd70 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1fd80 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1fd90 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1fda0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1fdb0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1fdc0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1fdd0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1fde0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1fdf0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1fe00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1fe10 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1fe20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1fe30 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1fe40 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1fe50 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1fe60 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1fe70 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1fe80 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1fe90 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1fea0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1feb0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1fec0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1fed0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1fee0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1fef0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1ff00 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1ff10 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1ff20 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1ff30 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1ff40 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1ff50 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1ff60 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1ff70 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1ff80 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1ff90 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1ffa0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1ffb0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1ffc0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1ffd0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1ffe0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1fff0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
20000 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
20010 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
20020 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
20030 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
20040 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
20050 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
20060 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
20070 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
20080 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
20090 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
200a0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
200b0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
200c0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
200d0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
200e0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
200f0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
20100 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
20110 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
20120 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
20130 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
20140 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
20150 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
20160 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
20170 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
20180 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
20190 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
201a0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
201b0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
201c0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
201d0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
201e0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
201f0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
20200 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
20210 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
20220 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20230 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
20240 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
20250 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
20260 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20270 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
20280 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20290 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
202a0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
202b0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
202c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
202d0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
202e0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
202f0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
20300 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
20310 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
20320 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
20330 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
20340 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
20350 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
20360 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
20370 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
20380 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
20390 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
203a0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
203b0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
203c0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
203d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
203e0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
203f0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
20400 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20410 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
20420 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
20430 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
20440 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
20450 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
20460 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
20470 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
20480 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
20490 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
204a0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
204b0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
204c0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
204d0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
204e0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
204f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
20500 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
20510 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
20520 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
20530 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
20540 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
20550 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
20560 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
20570 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
20580 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
20590 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
205a0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
205b0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
205c0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
205d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
205e0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
205f0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
20600 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
20610 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
20620 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
20630 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
20640 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
20650 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
20660 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
20670 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
20680 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
20690 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
206a0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
206b0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
206c0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
206d0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
206e0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
206f0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
20700 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
20710 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
20720 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
20730 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
20740 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
20750 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
20760 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
20770 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
20780 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
20790 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
207a0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
207b0 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
207c0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
207d0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
207e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
207f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20800 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
20810 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
20820 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
20830 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
20840 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
20850 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
20860 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
20870 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
20880 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
20890 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
208a0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
208b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
208c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
208d0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
208e0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
208f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
20900 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
20910 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
20920 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
20930 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
20940 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
20950 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
20960 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
20970 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
20980 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
20990 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
209a0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
209b0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
209c0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
209d0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
209e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
209f0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
20a00 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
20a10 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
20a20 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
20a30 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
20a40 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
20a50 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
20a60 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
20a70 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
20a80 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
20a90 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
20aa0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
20ab0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
20ac0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
20ad0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
20ae0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
20af0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
20b00 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
20b10 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
20b20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20b30 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
20b40 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
20b50 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
20b60 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
20b70 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
20b80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
20b90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20ba0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
20bb0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
20bc0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
20bd0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
20be0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
20bf0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
20c00 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
20c10 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
20c20 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
20c30 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
20c40 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
20c50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20c60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20c70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
20c80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
20c90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
20ca0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20cb0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
20cc0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
20cd0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
20ce0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
20cf0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
20d00 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
20d10 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
20d20 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
20d30 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20d40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
20d50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
20d60 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
20d70 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
20d80 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
20d90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
20da0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
20db0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20dc0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20dd0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20de0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
20df0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
20e00 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
20e10 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
20e20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20e30 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
20e40 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
20e50 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
20e60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20e70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20e80 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
20e90 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
20ea0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
20eb0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20ec0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20ed0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
20ee0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
20ef0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
20f00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20f10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20f20 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
20f30 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
20f40 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20f50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20f60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20f70 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
20f80 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
20f90 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
20fa0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20fb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20fc0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
20fd0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
20fe0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
20ff0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21000 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21010 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
21020 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
21030 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
21040 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21060 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
21070 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
21080 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21090 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
210a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
210b0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
210c0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
210d0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
210e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
210f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
21100 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
21110 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
21120 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21130 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21140 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21150 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
21160 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
21170 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
21180 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21190 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
211a0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
211b0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
211c0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
211d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
211e0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
211f0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
21200 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
21210 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21220 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21230 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
21240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
21250 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
21260 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
21270 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
21280 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
21290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
212a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
212b0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
212c0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
212d0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
212e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
212f0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
21300 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21310 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21320 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
21330 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
21340 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
21350 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21360 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21370 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
21380 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
21390 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
213a0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
213b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
213c0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
213d0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
213e0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
213f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21400 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21410 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
21420 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
21430 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
21440 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21450 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21460 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
21470 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
21480 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
21490 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
214a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
214b0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
214c0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
214d0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
214e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
214f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21500 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
21510 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
21520 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21530 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21550 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
21560 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
21570 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
21580 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
21590 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
215a0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
215b0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
215c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
215d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
215e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
215f0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
21600 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
21610 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
21620 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
21630 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
21640 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
21650 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
21660 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
21670 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
21680 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
21690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
216a0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
216b0 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
216c0 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
216d0 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
216e0 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
216f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21700 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
21710 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
21720 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
21730 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
21740 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
21750 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
21760 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
21770 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
21780 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
21790 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
217a0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
217b0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
217c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
217d0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
217e0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
217f0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
21800 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
21810 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
21820 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
21830 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
21840 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
21850 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
21860 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
21870 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
21880 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
21890 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
218a0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
218b0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
218c0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
218d0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
218e0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
218f0 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
21900 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
21910 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
21920 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
21930 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
21940 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
21950 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
21960 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
21970 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
21980 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
21990 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
219a0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
219b0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
219c0 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
219d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
219e0 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
219f0 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
21a00 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
21a10 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
21a20 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
21a30 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
21a40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
21a50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
21a60 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
21a70 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
21a80 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
21a90 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
21aa0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
21ab0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
21ac0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
21ad0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
21ae0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
21af0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
21b00 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
21b10 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
21b20 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
21b30 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
21b40 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
21b50 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
21b60 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
21b70 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
21b80 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
21b90 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
21ba0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
21bb0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
21bc0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
21bd0 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
21be0 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
21bf0 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
21c00 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
21c10 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
21c20 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
21c30 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
21c40 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
21c50 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
21c60 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
21c70 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
21c80 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
21c90 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
21ca0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
21cb0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
21cc0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
21cd0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
21ce0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
21cf0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
21d00 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
21d10 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
21d20 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
21d30 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
21d40 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
21d50 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
21d60 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
21d70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
21d80 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
21d90 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
21da0 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
21db0 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
21dc0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
21dd0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
21de0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
21df0 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
21e00 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
21e10 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
21e20 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
21e30 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
21e40 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
21e50 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
21e60 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
21e70 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
21e80 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
21e90 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
21ea0 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
21eb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
21ec0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
21ed0 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
21ee0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
21ef0 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
21f00 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
21f10 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
21f20 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
21f30 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
21f40 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
21f50 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
21f60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21f70 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
21f80 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61  meter N is the a
21f90 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65  pproximate numbe
21fa0 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
21fb0 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
21fc0 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
21fd0 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
21fe0 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
21ff0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
22000 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20  the callback X. 
22010 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74   ^If N is less t
22020 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65  han one then the
22030 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e   progress.** han
22040 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  dler is disabled
22050 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
22060 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
22070 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
22080 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
22090 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
220a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
220b0 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
220c0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
220d0 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
220e0 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
220f0 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
22100 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
22110 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
22120 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
22130 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
22140 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
22150 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
22160 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
22170 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
22180 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
22190 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
221a0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
221b0 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
221c0 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
221d0 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
221e0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
221f0 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
22200 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
22210 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
22220 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
22230 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
22240 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
22250 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
22260 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
22270 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22280 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
22290 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
222a0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
222b0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
222c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
222d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
222e0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
222f0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
22300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
22310 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
22320 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
22330 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
22340 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
22350 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
22360 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
22370 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
22380 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
22390 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
223a0 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
223b0 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f  Connection.** CO
223c0 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
223d0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
223e0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
223f0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
22400 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
22410 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
22420 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
22430 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
22440 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
22450 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
22460 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
22470 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
22480 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
22490 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
224a0 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
224b0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
224c0 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
224d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
224e0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
224f0 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
22500 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
22510 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
22520 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
22530 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
22540 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
22550 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
22560 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
22570 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
22580 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
22590 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
225a0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
225b0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
225c0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
225d0 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
225e0 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
225f0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
22600 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
22610 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
22620 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
22630 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
22640 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
22650 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
22660 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
22670 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
22680 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
22690 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
226a0 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
226b0 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
226c0 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
226d0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
226e0 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
226f0 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
22700 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
22710 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
22720 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
22730 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
22740 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46  ding will be UTF
22750 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  -8 for databases
22760 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
22770 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
22780 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
22790 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66  _v2().  ^The def
227a0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
227b0 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63  r databases.** c
227c0 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c  reated using sql
227d0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69  ite3_open16() wi
227e0 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20  ll be UTF-16 in 
227f0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
22800 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  order..**.** Whe
22810 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
22820 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
22830 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
22840 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
22850 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
22860 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
22870 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
22880 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
22890 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
228a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
228b0 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
228c0 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
228d0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
228e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
228f0 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
22900 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
22910 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
22920 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
22930 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
22940 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
22950 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
22960 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
22970 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22980 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
22990 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
229a0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
229b0 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
229c0 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
229d0 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
229e0 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
229f0 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
22a00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
22a10 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
22a20 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
22a30 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
22a40 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
22a50 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
22a60 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
22a70 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
22a80 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
22a90 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
22aa0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
22ab0 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
22ac0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
22ad0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
22ae0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
22af0 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
22b00 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
22b10 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
22b20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
22b30 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
22b40 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
22b50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
22b60 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
22b70 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
22b80 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
22b90 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
22ba0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
22bb0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
22bc0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
22bd0 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
22be0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
22bf0 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
22c00 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
22c10 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
22c20 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
22c30 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
22c40 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
22c50 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
22c60 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
22c70 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
22c80 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
22c90 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
22ca0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
22cb0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
22cc0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
22cd0 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
22ce0 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
22cf0 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
22d00 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
22d10 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
22d20 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
22d30 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
22d40 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
22d50 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
22d60 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
22d70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
22d80 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
22d90 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
22da0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
22db0 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
22dc0 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
22dd0 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
22de0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
22df0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
22e00 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
22e10 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
22e20 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
22e30 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
22e40 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
22e50 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
22e60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22e70 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
22e80 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
22e90 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
22ea0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
22eb0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
22ec0 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
22ed0 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
22ee0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
22ef0 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
22f00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
22f10 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
22f20 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
22f30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22f40 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
22f50 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
22f60 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
22f70 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
22f80 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
22f90 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
22fa0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
22fb0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
22fc0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
22fd0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
22fe0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
22ff0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23000 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
23010 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
23020 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
23030 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
23040 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
23050 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
23060 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
23070 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
23080 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
23090 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
230a0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
230b0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
230c0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
230d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
230e0 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
230f0 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
23100 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
23110 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
23120 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
23130 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
23140 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
23150 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
23160 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
23170 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
23180 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
23190 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
231a0 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
231b0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
231c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
231d0 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
231e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
231f0 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
23200 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
23210 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
23220 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
23230 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
23240 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
23250 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
23260 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
23270 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
23280 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
23290 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
232a0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
232b0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
232c0 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
232d0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
232e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
232f0 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
23300 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
23310 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
23320 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
23330 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
23340 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
23350 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
23360 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
23370 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
23380 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
23390 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
233a0 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
233b0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
233c0 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
233d0 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
233e0 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
233f0 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
23400 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
23410 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
23420 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
23430 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
23440 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
23450 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
23460 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
23470 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
23480 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
23490 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
234a0 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
234b0 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
234c0 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
234d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
234e0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
234f0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
23500 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
23510 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
23520 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
23530 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
23540 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
23550 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
23560 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
23570 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
23580 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
23590 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
235a0 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
235b0 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
235c0 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
235d0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
235e0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
235f0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
23600 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
23610 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
23620 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
23630 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
23640 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
23650 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
23660 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
23670 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
23680 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
23690 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
236a0 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
236b0 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
236c0 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
236d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
236e0 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
236f0 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
23700 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
23710 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
23720 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
23730 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
23740 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
23750 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
23760 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
23770 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
23780 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
23790 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
237a0 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
237b0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
237c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
237d0 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
237e0 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
237f0 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
23800 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
23810 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
23820 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
23830 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
23840 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
23850 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
23860 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
23870 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
23880 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
23890 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
238a0 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
238b0 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
238c0 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
238d0 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
238e0 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
238f0 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
23900 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
23910 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
23920 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
23930 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
23940 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
23950 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
23960 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
23970 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
23980 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
23990 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
239a0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
239b0 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
239c0 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
239d0 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
239e0 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
239f0 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
23a00 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
23a10 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
23a20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
23a30 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
23a40 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
23a50 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
23a60 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28  ive path. .** ^(
23a70 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
23a80 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
23a90 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
23aa0 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
23ab0 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
23ac0 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a   (e.g. "C:").)^.
23ad0 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
23ae0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23af0 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
23b00 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
23b10 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
23b20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
23b30 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
23b40 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
23b50 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
23b60 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
23b70 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
23b80 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
23b90 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69   and its built-i
23ba0 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70  n [VFSes] interp
23bb0 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ret the.** follo
23bc0 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
23bd0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
23be0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
23bf0 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
23c00 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
23c10 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
23c20 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
23c30 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
23c40 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
23c50 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
23c60 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
23c70 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
23c80 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
23c90 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
23ca0 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
23cb0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
23cc0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
23cd0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
23ce0 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
23cf0 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
23d00 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
23d10 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
23d20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
23d30 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
23d40 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
23d50 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
23d60 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
23d70 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
23d80 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
23d90 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
23da0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
23db0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
23dc0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
23dd0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
23de0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
23df0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
23e00 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
23e10 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
23e20 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
23e30 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
23e40 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
23e50 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
23e60 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
23e70 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
23e80 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
23e90 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
23ea0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
23eb0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
23ec0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
23ed0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
23ee0 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
23ef0 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
23f00 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
23f10 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
23f20 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
23f30 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
23f40 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
23f50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23f60 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
23f70 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
23f80 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
23f90 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
23fa0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
23fb0 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
23fc0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
23fd0 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
23fe0 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
23ff0 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
24000 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
24010 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
24020 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
24030 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
24040 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
24050 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
24060 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24070 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
24080 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
24090 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
240a0 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
240b0 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
240c0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
240d0 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
240e0 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
240f0 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
24100 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
24110 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
24120 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
24130 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
24140 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
24150 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
24160 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
24170 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
24180 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
24190 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
241a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
241b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
241c0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
241d0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
241e0 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
241f0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
24200 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
24210 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
24220 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
24230 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
24240 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
24250 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
24260 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
24270 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
24280 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
24290 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
242a0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
242b0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
242c0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
242d0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
242e0 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
242f0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
24300 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
24310 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24320 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
24330 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
24340 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
24350 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
24360 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
24370 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
24380 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
24390 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
243a0 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
243b0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
243c0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
243d0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
243e0 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
243f0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
24400 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
24410 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
24420 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
24430 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68   indicates wheth
24440 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a  er or not the.**
24450 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
24460 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
24470 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
24480 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
24490 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
244a0 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
244b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
244c0 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a  e resides..**.**
244d0 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
244e0 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
244f0 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
24500 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
24510 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
24520 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
24530 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
24540 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
24550 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
24560 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
24570 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
24580 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
24590 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
245a0 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
245b0 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
245c0 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
245d0 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
245e0 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
245f0 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
24600 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
24610 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
24620 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
24630 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
24640 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
24650 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
24660 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
24670 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
24680 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
24690 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
246a0 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
246b0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
246c0 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
246d0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
246e0 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
246f0 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
24700 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
24710 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
24720 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
24730 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
24740 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
24750 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
24760 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
24770 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
24780 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
24790 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
247a0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
247b0 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
247c0 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
247d0 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
247e0 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
247f0 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
24800 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
24810 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
24820 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
24830 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
24840 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
24850 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
24860 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
24870 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
24880 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
24890 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
248a0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
248b0 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
248c0 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
248d0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
248e0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
248f0 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
24900 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
24910 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
24920 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
24930 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
24940 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
24950 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
24960 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
24970 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
24980 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
24990 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
249a0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
249b0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
249c0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
249d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
249e0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
249f0 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
24a00 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
24a10 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
24a20 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
24a30 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
24a40 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
24a50 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
24a60 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
24a70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
24a80 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
24a90 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
24aa0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
24ab0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
24ac0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
24ad0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
24ae0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
24af0 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
24b00 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
24b10 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
24b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
24b30 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
24b40 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
24b50 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
24b60 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
24b70 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
24b80 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24b90 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
24ba0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
24bb0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24bc0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
24bd0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
24be0 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
24bf0 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
24c00 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
24c10 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
24c20 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
24c30 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
24c40 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
24c50 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
24c60 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
24c70 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
24c80 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
24c90 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
24ca0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
24cb0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
24cc0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
24cd0 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
24ce0 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
24cf0 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
24d00 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
24d10 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
24d20 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
24d30 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
24d40 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
24d50 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
24d60 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
24d70 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
24d80 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
24d90 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
24da0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
24db0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
24dc0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
24dd0 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
24de0 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
24df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
24e00 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
24e10 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
24e20 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
24e30 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
24e40 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
24e50 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
24e60 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
24e70 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
24e80 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
24e90 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
24ea0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
24eb0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
24ec0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
24ed0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
24ee0 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
24ef0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
24f00 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
24f10 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
24f20 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
24f30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
24f40 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
24f50 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
24f60 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
24f70 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
24f80 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
24f90 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
24fa0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
24fb0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
24fc0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
24fd0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
24fe0 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
24ff0 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
25000 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
25010 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
25020 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
25030 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
25040 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
25050 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
25060 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
25070 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
25080 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
25090 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
250a0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
250b0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
250c0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
250d0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
250e0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
250f0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
25100 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
25110 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
25120 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
25130 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
25140 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
25150 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
25160 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
25170 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
25180 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
25190 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
251a0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
251b0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
251c0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
251d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
251e0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
251f0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
25200 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
25210 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
25220 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
25230 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
25240 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
25250 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
25260 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
25270 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
25280 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
25290 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
252a0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
252b0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
252c0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
252d0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
252e0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
252f0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
25300 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
25310 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
25320 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
25330 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
25340 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
25350 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
25360 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
25370 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
25380 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
25390 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
253a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
253b0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
253c0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
253d0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
253e0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
253f0 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
25400 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
25410 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
25420 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
25430 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
25440 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
25450 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
25460 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
25470 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
25480 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
25490 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
254a0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
254b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
254c0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
254d0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
254e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
254f0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
25500 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
25510 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
25520 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
25530 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
25540 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
25550 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
25560 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
25570 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
25580 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
25590 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
255a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
255b0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
255c0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
255d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
255e0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
255f0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
25600 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
25610 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
25620 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25630 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
25640 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
25650 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
25660 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
25670 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
25680 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
25690 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
256a0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
256b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
256c0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
256d0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
256e0 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
256f0 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
25700 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
25710 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
25720 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
25730 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
25740 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
25750 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
25760 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
25770 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
25780 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
25790 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
257a0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
257b0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
257c0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
257d0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
257e0 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
257f0 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
25800 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
25810 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
25820 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
25830 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
25840 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
25850 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
25860 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
25870 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
25880 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
25890 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
258a0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
258b0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
258c0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
258d0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
258e0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
258f0 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
25900 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
25910 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
25920 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
25930 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
25940 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
25950 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
25960 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
25970 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
25980 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
25990 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
259a0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
259b0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
259c0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
259d0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
259e0 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
259f0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
25a00 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
25a10 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
25a20 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
25a30 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
25a40 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
25a50 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
25a60 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
25a70 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
25a80 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
25a90 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
25aa0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
25ab0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
25ac0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
25ad0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
25ae0 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
25af0 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
25b00 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
25b10 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
25b20 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
25b30 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
25b40 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
25b50 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
25b60 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
25b70 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
25b80 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
25b90 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
25ba0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
25bb0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
25bc0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
25bd0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
25be0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
25bf0 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
25c00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
25c10 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
25c20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
25c30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
25c40 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
25c50 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
25c60 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
25c70 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
25c80 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
25c90 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
25ca0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
25cb0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
25cc0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
25cd0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
25ce0 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
25cf0 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
25d00 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
25d10 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
25d20 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
25d30 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
25d40 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
25d50 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
25d60 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
25d70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
25d80 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
25d90 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
25da0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
25db0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
25dc0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
25dd0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
25de0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
25df0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
25e00 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
25e10 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
25e20 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
25e30 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25e40 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
25e50 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
25e60 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
25e70 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
25e80 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
25e90 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
25ea0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
25eb0 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
25ec0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
25ed0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
25ee0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
25ef0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
25f00 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
25f10 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
25f20 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
25f30 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
25f40 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
25f50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
25f60 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
25f70 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
25f80 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
25f90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
25fa0 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
25fb0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
25fc0 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
25fd0 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
25fe0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
25ff0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
26000 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
26010 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
26020 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49  * API call..** I
26030 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
26040 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73  t API call was s
26050 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68  uccessful,.** th
26060 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
26070 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
26080 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
26090 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  defined..** ^The
260a0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
260b0 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
260c0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
260d0 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
260e0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
260f0 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
26100 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
26110 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
26120 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
26130 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
26140 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
26150 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
26160 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
26170 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
26180 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
26190 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
261a0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
261b0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
261c0 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
261d0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
261e0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
261f0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
26200 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
26210 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
26220 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
26230 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
26240 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
26250 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
26260 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
26270 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
26280 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
26290 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
262a0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
262b0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
262c0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
262d0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
262e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
262f0 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
26300 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
26310 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
26320 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
26330 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
26340 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
26350 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
26360 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
26370 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
26380 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
26390 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
263a0 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
263b0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
263c0 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
263d0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
263e0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
263f0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
26400 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
26410 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
26420 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
26430 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
26440 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
26450 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
26460 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
26470 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
26480 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
26490 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
264a0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
264b0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
264c0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
264d0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
264e0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
264f0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
26500 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
26510 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
26520 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
26530 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
26540 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
26550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
26560 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
26570 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
26580 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
26590 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
265a0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
265b0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
265c0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
265d0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
265e0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
265f0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
26600 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
26610 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
26620 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
26630 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
26640 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
26650 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
26660 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
26670 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
26680 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
26690 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
266a0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
266b0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
266c0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
266d0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
266e0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
266f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
26700 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
26710 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
26720 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
26730 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
26740 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
26750 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
26760 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
26770 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
26780 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  16(sqlite3*);.co
26790 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
267a0 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
267b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
267c0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
267d0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
267e0 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
267f0 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
26800 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
26810 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
26820 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
26830 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
26840 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
26850 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73  ment that.** has
26860 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69   been compiled i
26870 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20  nto binary form 
26880 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20  and is ready to 
26890 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a  be evaluated..**
268a0 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63  .** Think of eac
268b0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
268c0 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f  as a separate co
268d0 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20  mputer program. 
268e0 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   The.** original
268f0 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75   SQL text is sou
26900 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65  rce code.  A pre
26910 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
26920 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68  object .** is th
26930 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63  e compiled objec
26940 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c  t code.  All SQL
26950 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
26960 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65  ed into a.** pre
26970 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
26980 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65  before it can be
26990 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
269a0 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20  life-cycle of a 
269b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
269c0 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c  nt object usuall
269d0 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73  y goes like this
269e0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
269f0 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
26a00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26a10 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  nt object using 
26a20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26a30 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  _v2()]..** <li> 
26a40 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
26a50 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
26a60 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
26a70 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
26a80 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
26a90 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
26aa0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
26ab0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
26ac0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
26ad0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
26ae0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26af0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
26b00 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
26b10 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
26b20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
26b30 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
26b40 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
26b50 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
26b60 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
26b70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
26b80 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64  * </ol>.*/.typed
26b90 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
26ba0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
26bb0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
26bc0 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
26bd0 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  imits.** METHOD:
26be0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
26bf0 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
26c00 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
26c10 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
26c20 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
26c30 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
26c40 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
26c50 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
26c60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
26c70 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
26c80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
26c90 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
26ca0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
26cb0 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
26cc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
26cd0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
26ce0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
26cf0 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
26d00 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
26d10 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
26d20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
26d30 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
26d40 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
26d50 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
26d60 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
26d70 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
26d80 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
26d90 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
26da0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
26db0 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
26dc0 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
26dd0 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
26de0 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
26df0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
26e00 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
26e10 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
26e20 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
26e30 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
26e40 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
26e50 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
26e60 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
26e70 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
26e80 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
26e90 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
26ea0 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
26eb0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
26ec0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
26ed0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
26ee0 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
26ef0 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
26f00 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
26f10 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
26f20 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
26f30 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
26f40 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
26f50 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
26f60 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
26f70 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
26f80 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
26f90 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
26fa0 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
26fb0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
26fc0 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
26fd0 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
26fe0 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
26ff0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
27000 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
27010 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
27020 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
27030 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
27040 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
27050 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
27060 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
27070 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
27080 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
27090 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
270a0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
270b0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
270c0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
270d0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
270e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
270f0 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
27100 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
27110 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
27120 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
27130 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
27140 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
27150 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
27160 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
27170 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
27180 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
27190 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
271a0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
271b0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
271c0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
271d0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
271e0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
271f0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
27200 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
27210 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
27220 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
27230 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
27240 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
27250 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
27260 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
27270 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
27280 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
27290 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
272a0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
272b0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
272c0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
272d0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
272e0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
272f0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
27300 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
27310 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
27320 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
27330 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
27340 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
27350 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
27360 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
27370 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
27380 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
27390 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
273a0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
273b0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
273c0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
273d0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
273e0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
273f0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
27400 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
27410 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
27420 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
27430 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
27440 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
27450 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
27460 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
27470 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
27480 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
27490 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
274a0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
274b0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
274c0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
274d0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
274e0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
274f0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
27500 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
27510 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
27520 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27530 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
27540 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
27550 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
27560 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
27570 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
27580 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
27590 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
275a0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
275b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
275c0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
275d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
275e0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
275f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
27600 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
27610 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
27620 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
27630 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27640 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
27650 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
27660 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
27670 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
27680 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
27690 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
276a0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
276b0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
276c0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
276d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
276e0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
276f0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
27700 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
27710 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
27720 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
27730 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
27740 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
27750 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
27760 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
27770 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
27780 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
27790 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
277a0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
277b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
277c0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
277d0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
277e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
277f0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
27800 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
27810 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
27820 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
27830 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
27840 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
27850 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
27860 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
27870 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
27880 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
27890 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
278a0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
278b0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
278c0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
278d0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
278e0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
278f0 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
27900 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
27910 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
27920 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
27930 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
27940 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
27950 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
27960 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
27970 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
27980 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
27990 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
279a0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
279b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
279c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
279d0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
279e0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
279f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27a00 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
27a10 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27a20 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
27a30 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
27a40 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
27a50 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
27a60 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
27a70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27a80 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
27a90 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
27aa0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
27ab0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
27ac0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
27ad0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
27ae0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
27af0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
27b00 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
27b10 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
27b20 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
27b30 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
27b40 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
27b50 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
27b60 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
27b70 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
27b80 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
27b90 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
27ba0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
27bb0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
27bc0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
27bd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
27be0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
27bf0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
27c00 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
27c10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27c20 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
27c30 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
27c40 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
27c50 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27c60 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
27c70 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27c80 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
27c90 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
27ca0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
27cb0 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
27cc0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
27cd0 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
27ce0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27cf0 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
27d00 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
27d10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
27d20 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
27d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27d40 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
27d50 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
27d60 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
27d70 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
27d80 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
27d90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27da0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
27db0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
27dc0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
27dd0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
27de0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
27df0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
27e00 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
27e10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
27e20 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
27e30 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
27e40 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
27e50 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
27e60 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
27e70 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
27e80 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
27e90 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
27ea0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27eb0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
27ec0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
27ed0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27ee0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
27ef0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
27f00 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27f10 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
27f20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
27f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27f40 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
27f50 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
27f60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27f70 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
27f80 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
27f90 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
27fa0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
27fb0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
27fc0 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  te3.** CONSTRUCT
27fd0 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
27fe0 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
27ff0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
28000 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
28010 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
28020 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
28030 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
28040 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
28050 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
28060 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
28070 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
28080 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
28090 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
280a0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
280b0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
280c0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
280d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
280e0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
280f0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
28100 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28110 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
28120 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
28130 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
28140 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
28150 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
28160 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
28170 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
28180 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
28190 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
281a0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
281b0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
281c0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
281d0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
281e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
281f0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
28200 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28210 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
28220 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
28230 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
28240 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
28250 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
28260 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
28270 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
28280 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
28290 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
282a0 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
282b0 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
282c0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
282d0 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
282e0 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
282f0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
28300 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
28310 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
28320 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
28330 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
28340 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
28350 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
28360 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
28370 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
28380 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
28390 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
283a0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
283b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
283c0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
283d0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
283e0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
283f0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
28400 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
28410 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
28420 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
28430 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
28440 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
28450 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
28460 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
28470 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
28480 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
28490 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
284a0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
284b0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
284c0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
284d0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
284e0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
284f0 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
28500 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
28510 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
28520 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28530 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
28540 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
28550 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
28560 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
28570 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
28580 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
28590 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
285a0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
285b0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
285c0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
285d0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
285e0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
285f0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
28600 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
28610 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
28620 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
28630 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
28640 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
28650 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
28660 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
28670 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
28680 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
28690 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
286a0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
286b0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
286c0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
286d0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
286e0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
286f0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
28700 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
28710 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
28720 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
28730 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
28740 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
28750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28760 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
28770 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
28780 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
28790 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
287a0 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
287b0 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
287c0 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
287d0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
287e0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
287f0 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
28800 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
28810 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
28820 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
28830 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
28840 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
28850 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
28860 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
28870 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
28880 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
28890 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
288a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
288b0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
288c0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
288d0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
288e0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
288f0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
28900 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
28910 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
28920 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
28930 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
28940 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
28950 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
28960 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
28970 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
28980 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
28990 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
289a0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
289b0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
289c0 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
289d0 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
289e0 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
289f0 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
28a00 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
28a10 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
28a20 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
28a30 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
28a40 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
28a50 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
28a60 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
28a70 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
28a80 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
28a90 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
28aa0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
28ab0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
28ac0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
28ad0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
28ae0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
28af0 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
28b00 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
28b10 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
28b20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
28b30 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
28b40 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
28b50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
28b60 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
28b70 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
28b80 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
28b90 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
28ba0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
28bb0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
28bc0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
28bd0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
28be0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
28bf0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
28c00 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
28c10 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
28c20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
28c30 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
28c40 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
28c50 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
28c60 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
28c70 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
28c80 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
28c90 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
28ca0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
28cb0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
28cc0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
28cd0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
28ce0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
28cf0 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
28d00 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
28d10 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
28d20 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
28d30 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
28d40 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
28d50 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
28d60 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
28d70 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
28d80 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
28d90 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
28da0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
28db0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
28dc0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
28dd0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
28de0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
28df0 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
28e00 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
28e10 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
28e20 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
28e30 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
28e40 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
28e50 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
28e60 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
28e70 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
28e80 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
28e90 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
28ea0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
28eb0 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
28ec0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
28ed0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
28ee0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
28ef0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28f00 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
28f10 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
28f20 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
28f30 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
28f40 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
28f50 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
28f60 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
28f70 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
28f80 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
28f90 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
28fa0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
28fb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
28fc0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
28fd0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
28fe0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
28ff0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
29000 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
29010 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
29020 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
29030 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
29040 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
29050 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
29060 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
29070 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
29080 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
29090 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
290a0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
290b0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
290c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
290d0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
290e0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
290f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
29100 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
29110 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
29120 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
29130 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
29140 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
29150 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
29160 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
29170 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
29180 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
29190 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
291a0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
291b0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
291c0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
291d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
291e0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
291f0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
29200 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
29210 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
29220 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
29230 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
29240 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
29250 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
29260 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
29270 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
29280 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
29290 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
292a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
292b0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
292c0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
292d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
292e0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
292f0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
29300 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
29310 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
29320 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
29330 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
29340 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
29350 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
29360 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
29370 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
29380 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
29390 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
293a0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
293b0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
293c0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
293d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
293e0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
293f0 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44  nt SQL.** METHOD
29400 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
29410 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
29420 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
29430 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
29440 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
29450 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
29460 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
29470 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
29480 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
29490 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
294a0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
294b0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
294c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
294d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
294e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
294f0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
29500 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
29510 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
29520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29530 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
29540 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
29550 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
29560 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  se.** METHOD: sq
29570 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
29580 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
29590 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
295a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
295b0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
295c0 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
295d0 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
295e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
295f0 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
29600 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
29610 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
29620 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
29630 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
29640 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29650 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
29660 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
29670 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
29680 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
29690 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
296a0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
296b0 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
296c0 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
296d0 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
296e0 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
296f0 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
29700 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
29710 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
29720 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
29730 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
29740 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
29750 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
29760 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
29770 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
29780 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
29790 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
297a0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
297b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
297c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
297d0 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
297e0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
297f0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
29800 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
29810 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
29820 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
29830 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
29840 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
29850 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
29860 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
29870 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
29880 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
29890 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
298a0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
298b0 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
298c0 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
298d0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
298e0 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
298f0 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
29900 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
29910 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
29920 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
29930 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
29940 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
29950 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
29960 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
29970 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
29980 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
29990 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
299a0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
299b0 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
299c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
299d0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
299e0 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
299f0 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
29a00 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
29a10 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
29a20 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
29a30 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
29a40 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
29a50 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
29a60 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
29a70 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
29a80 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  disk..*/.int sql
29a90 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
29aa0 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
29ab0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
29ac0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
29ad0 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65  ine If A Prepare
29ae0 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20  d Statement Has 
29af0 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45  Been Reset.** ME
29b00 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
29b10 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
29b20 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
29b30 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
29b40 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
29b50 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
29b60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29b70 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
29b80 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
29b90 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
29ba0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
29bb0 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72   but has neither
29bc0 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
29bd0 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20  on (returned.** 
29be0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72  [SQLITE_DONE] fr
29bf0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  om [sqlite3_step
29c00 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65  (S)]) nor.** bee
29c10 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
29c20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
29c30 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
29c40 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
29c50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29c60 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
29c70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
29c80 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
29c90 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
29ca0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
29cb0 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
29cc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29cd0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
29ce0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
29cf0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
29d00 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
29d10 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
29d20 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
29d30 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
29d40 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
29d50 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
29d60 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
29d70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29d80 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
29d90 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
29da0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
29db0 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
29dc0 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
29dd0 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
29de0 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
29df0 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
29e00 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
29e10 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
29e20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
29e30 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
29e40 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
29e50 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  en..*/.int sqlit
29e60 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
29e70 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
29e80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
29e90 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
29ea0 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
29eb0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
29ec0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29ed0 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
29ee0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
29ef0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
29f00 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
29f10 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
29f20 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
29f30 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
29f40 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
29f50 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
29f60 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
29f70 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
29f80 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
29f90 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
29fa0 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
29fb0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
29fc0 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
29fd0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
29fe0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
29ff0 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
2a000 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
2a010 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2a020 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
2a030 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
2a040 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
2a050 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
2a060 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
2a070 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a080 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
2a090 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
2a0a0 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
2a0b0 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
2a0c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a0d0 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
2a0e0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
2a0f0 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
2a100 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
2a110 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
2a120 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
2a130 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
2a140 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a150 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
2a160 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d  te3_value_dup()]
2a170 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2a180 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72  e used to constr
2a190 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72  uct a new .** pr
2a1a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2a1b0 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e  value from an un
2a1c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a1d0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
2a1e0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
2a1f0 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
2a200 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
2a210 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
2a220 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
2a230 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
2a240 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2a250 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
2a260 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a270 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
2a280 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
2a290 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
2a2a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a2b0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
2a2c0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
2a2d0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
2a2e0 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
2a2f0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2a300 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
2a310 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2a320 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
2a330 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
2a340 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
2a350 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
2a360 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
2a370 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
2a380 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
2a390 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
2a3a0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
2a3b0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
2a3c0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2a3d0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2a3e0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2a3f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2a400 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
2a410 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
2a420 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
2a430 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
2a440 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
2a450 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
2a460 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
2a470 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
2a480 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
2a490 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
2a4a0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
2a4b0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2a4c0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
2a4d0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
2a4e0 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
2a4f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a500 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
2a510 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
2a520 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
2a530 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
2a540 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
2a550 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a560 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
2a570 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
2a580 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
2a590 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
2a5a0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2a5b0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2a5c0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
2a5d0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
2a5e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2a5f0 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
2a600 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
2a610 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2a620 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2a630 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2a640 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
2a650 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2a660 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
2a670 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
2a680 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
2a690 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
2a6a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2a6b0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
2a6c0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
2a6d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
2a6e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a6f0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
2a700 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
2a710 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
2a720 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
2a730 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
2a740 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
2a750 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
2a760 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
2a770 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
2a780 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2a790 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
2a7a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2a7b0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
2a7c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2a7d0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
2a7e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a7f0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2a800 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2a810 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
2a820 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
2a830 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
2a840 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2a850 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
2a860 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
2a870 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2a880 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
2a890 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2a8a0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
2a8b0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2a8c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
2a8d0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
2a8e0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
2a8f0 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
2a900 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2a910 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2a920 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2a930 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
2a940 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
2a950 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
2a960 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
2a970 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
2a980 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
2a990 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
2a9a0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
2a9b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2a9c0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
2a9d0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
2a9e0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2a9f0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2aa00 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2aa10 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
2aa20 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
2aa30 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
2aa40 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2aa50 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
2aa60 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
2aa70 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
2aa80 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
2aa90 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
2aaa0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
2aab0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
2aac0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
2aad0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
2aae0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
2aaf0 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
2ab00 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
2ab10 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
2ab20 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
2ab30 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
2ab40 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
2ab50 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
2ab60 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
2ab70 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
2ab80 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
2ab90 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
2aba0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
2abb0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
2abc0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
2abd0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
2abe0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
2abf0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2ac00 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2ac10 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
2ac20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2ac30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2ac40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2ac50 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
2ac60 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
2ac70 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
2ac80 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
2ac90 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
2aca0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2acb0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
2acc0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
2acd0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2ace0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2acf0 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
2ad00 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
2ad10 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
2ad20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
2ad30 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2ad40 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
2ad50 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
2ad60 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
2ad70 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
2ad80 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2ad90 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
2ada0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
2adb0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
2adc0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
2add0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
2ade0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
2adf0 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
2ae00 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
2ae10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2ae20 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2ae30 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
2ae40 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
2ae50 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
2ae60 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
2ae70 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
2ae80 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
2ae90 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
2aea0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
2aeb0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
2aec0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
2aed0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2aee0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
2aef0 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
2af00 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2af10 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2af20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
2af30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
2af40 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
2af50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2af60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2af70 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2af80 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
2af90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2afa0 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
2afb0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
2afc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2afd0 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
2afe0 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
2aff0 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
2b000 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2b010 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
2b020 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
2b030 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
2b040 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
2b050 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2b060 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2b070 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2b080 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
2b090 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
2b0a0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
2b0b0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
2b0c0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
2b0d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2b0e0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
2b0f0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2b100 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2b110 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2b120 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2b130 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
2b140 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
2b150 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
2b160 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
2b170 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
2b180 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
2b190 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
2b1a0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
2b1b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2b1c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2b1d0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2b1e0 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
2b1f0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2b200 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
2b210 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
2b220 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
2b230 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
2b240 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
2b250 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2b260 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33  t16() or sqlite3
2b270 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74  _bind_text64() t
2b280 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61  hen.** that para
2b290 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
2b2a0 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
2b2b0 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
2b2c0 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
2b2d0 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
2b2e0 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
2b2f0 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
2b300 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
2b310 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
2b320 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
2b330 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
2b340 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
2b350 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2b360 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
2b370 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
2b380 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
2b390 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
2b3a0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
2b3b0 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
2b3c0 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
2b3d0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
2b3e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2b3f0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
2b400 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2b410 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20  BLOB and string 
2b420 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63  binding interfac
2b430 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72  es.** is a destr
2b440 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
2b450 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2b460 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
2b470 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
2b480 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2b490 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
2b4a0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
2b4b0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2b4c0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
2b4d0 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
2b4e0 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61  l to bind API fa
2b4f0 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ils..** ^If the 
2b500 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
2b510 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
2b520 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
2b530 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
2b540 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
2b550 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
2b560 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
2b570 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
2b580 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
2b590 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
2b5a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2b5b0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
2b5c0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
2b5d0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
2b5e0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
2b5f0 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
2b600 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
2b610 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
2b620 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
2b630 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2b640 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
2b650 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2b660 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2b670 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2b680 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  () must be one o
2b690 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  f.** [SQLITE_UTF
2b6a0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2b6b0 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
2b6c0 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
2b6d0 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20  _UTF16LE].** to 
2b6e0 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f  specify the enco
2b6f0 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74  ding of the text
2b700 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
2b710 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20  rameter.  If.** 
2b720 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  the sixth argume
2b730 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2b740 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e  nd_text64() is n
2b750 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
2b760 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
2b770 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20  shown above, or 
2b780 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  if the text enco
2b790 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2b7a0 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e  t.** from the en
2b7b0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
2b7c0 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61   by the sixth pa
2b7d0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
2b7e0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
2b7f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2b800 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2b810 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
2b820 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
2b830 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
2b840 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
2b850 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
2b860 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
2b870 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
2b880 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
2b890 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
2b8a0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
2b8b0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
2b8c0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
2b8d0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
2b8e0 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
2b8f0 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
2b900 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
2b910 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
2b920 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
2b930 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
2b940 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
2b950 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
2b960 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
2b970 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
2b980 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
2b990 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
2b9a0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
2b9b0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
2b9c0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2b9d0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
2b9e0 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
2b9f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2ba00 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2ba10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
2ba20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
2ba30 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
2ba40 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
2ba50 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
2ba60 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
2ba70 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
2ba80 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
2ba90 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
2baa0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
2bab0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
2bac0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
2bad0 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
2bae0 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
2baf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2bb00 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
2bb10 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
2bb20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2bb30 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2bb40 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
2bb50 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
2bb60 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
2bb70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2bb80 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
2bb90 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
2bba0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
2bbb0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
2bbc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2bbd0 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
2bbe0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2bbf0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
2bc00 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2bc10 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
2bc20 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
2bc30 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d  SQLITE_TOOBIG] m
2bc40 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2bc50 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
2bc60 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2bc70 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69  .** exceeds limi
2bc80 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73  ts imposed by [s
2bc90 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2bca0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2bcb0 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  TH]) or.** [SQLI
2bcc0 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a  TE_MAX_LENGTH]..
2bcd0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
2bce0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
2bcf0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
2bd00 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
2bd10 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
2bd20 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
2bd30 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
2bd40 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
2bd50 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2bd60 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2bd70 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
2bd80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bd90 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2bda0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2bdb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2bdc0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2bdd0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
2bde0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2bdf0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2be00 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
2be10 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2be20 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28  te3_bind_blob64(
2be30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2be40 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2be50 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2be60 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2be70 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2be80 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2be90 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
2bea0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2beb0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
2bec0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2bed0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2bee0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
2bef0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2bf00 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2bf10 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2bf20 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
2bf30 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
2bf40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2bf50 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
2bf60 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
2bf70 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73  3_stmt*,int,cons
2bf80 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64  t char*,int,void
2bf90 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2bfa0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2bfb0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2bfc0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2bfd0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2bfe0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2bff0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2c000 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2c010 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
2c020 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  ar*, sqlite3_uin
2c030 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2c040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2c050 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
2c060 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
2c070 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ding);.int sqlit
2c080 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
2c090 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c0a0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
2c0b0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2c0c0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2c0d0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2c0e0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69  , int, int n);.i
2c0f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2c100 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74  zeroblob64(sqlit
2c110 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2c120 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
2c130 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c140 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
2c150 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54  arameters.** MET
2c160 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2c170 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
2c180 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
2c190 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
2c1a0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
2c1b0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
2c1c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c1d0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
2c1e0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
2c1f0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
2c200 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
2c210 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
2c220 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
2c230 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
2c240 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
2c250 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
2c260 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2c270 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
2c280 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
2c290 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
2c2a0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2c2b0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
2c2c0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2c2d0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
2c2e0 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
2c2f0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
2c300 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
2c310 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
2c320 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
2c330 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
2c340 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
2c350 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2c360 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
2c370 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
2c380 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
2c390 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
2c3a0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2c3b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2c3c0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2c3d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2c3e0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2c3f0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2c400 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c410 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2c420 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2c430 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
2c440 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2c450 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c460 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
2c470 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48  arameter.** METH
2c480 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2c490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c4a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2c4b0 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
2c4c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2c4d0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
2c4e0 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
2c4f0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
2c500 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c510 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
2c520 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2c530 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
2c540 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2c550 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
2c560 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
2c570 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
2c580 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2c590 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2c5a0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
2c5b0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
2c5c0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
2c5d0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
2c5e0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
2c5f0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
2c600 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
2c610 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
2c620 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
2c630 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
2c640 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
2c650 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
2c660 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
2c670 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
2c680 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
2c690 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
2c6a0 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
2c6b0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2c6c0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
2c6d0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
2c6e0 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
2c6f0 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
2c700 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
2c710 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
2c720 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
2c730 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
2c740 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2c750 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
2c760 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
2c770 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
2c780 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
2c790 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
2c7a0 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
2c7b0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
2c7c0 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
2c7d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c7e0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2c7f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2c800 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2c810 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2c820 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2c830 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2c840 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2c850 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c860 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
2c870 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2c880 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c890 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
2c8a0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
2c8b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
2c8c0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
2c8d0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
2c8e0 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ame.** METHOD: s
2c8f0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c900 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
2c910 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
2c920 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
2c930 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
2c940 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
2c950 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
2c960 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
2c970 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
2c980 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2c990 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2c9a0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
2c9b0 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
2c9c0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
2c9d0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
2c9e0 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
2c9f0 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
2ca00 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
2ca10 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
2ca20 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
2ca30 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
2ca40 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
2ca50 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
2ca60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2ca70 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2ca80 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2ca90 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2caa0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2cab0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2cac0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2cad0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2cae0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2caf0 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  me()]..*/.int sq
2cb00 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2cb10 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
2cb20 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
2cb30 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
2cb40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2cb50 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
2cb60 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
2cb70 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
2cb80 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2cb90 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
2cba0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
2cbb0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
2cbc0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
2cbd0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
2cbe0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2cbf0 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
2cc00 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
2cc10 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2cc20 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
2cc30 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
2cc40 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2cc50 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
2cc60 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2cc70 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2cc80 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2cc90 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2cca0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
2ccb0 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54  esult Set.** MET
2ccc0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2ccd0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2cce0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2ccf0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2cd00 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
2cd10 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
2cd20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2cd30 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
2cd40 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
2cd50 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
2cd60 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
2cd70 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
2cd80 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
2cd90 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
2cda0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2cdb0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2cdc0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
2cdd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2cde0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2cdf0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2ce00 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
2ce10 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
2ce20 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
2ce30 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2ce40 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2ce50 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
2ce60 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
2ce70 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
2ce80 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
2ce90 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2cea0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2ceb0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
2cec0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
2ced0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2cee0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2cef0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2cf00 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
2cf10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2cf20 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
2cf30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2cf40 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2cf50 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
2cf60 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
2cf70 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2cf80 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2cf90 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
2cfa0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
2cfb0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2cfc0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
2cfd0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
2cfe0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
2cff0 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
2d000 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
2d010 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
2d020 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2d030 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
2d040 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
2d050 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d060 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
2d070 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
2d080 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2d090 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2d0a0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2d0b0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2d0c0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2d0d0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2d0e0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2d0f0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2d100 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2d110 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
2d120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2d130 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
2d140 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2d150 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
2d160 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
2d170 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
2d180 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
2d190 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
2d1a0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
2d1b0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
2d1c0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
2d1d0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
2d1e0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
2d1f0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
2d200 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2d210 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
2d220 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2d230 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2d240 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
2d250 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
2d260 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
2d270 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
2d280 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
2d290 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
2d2a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
2d2b0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
2d2c0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
2d2d0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
2d2e0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
2d2f0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
2d300 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2d310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2d320 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d330 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
2d340 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2d350 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
2d360 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2d370 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d380 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
2d390 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
2d3a0 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
2d3b0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d3c0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2d3d0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
2d3e0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
2d3f0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
2d400 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
2d410 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
2d420 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
2d430 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
2d440 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
2d450 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2d460 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
2d470 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2d480 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
2d490 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
2d4a0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
2d4b0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
2d4c0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2d4d0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
2d4e0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
2d4f0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
2d500 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
2d510 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2d520 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
2d530 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
2d540 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2d550 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
2d560 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2d570 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
2d580 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
2d590 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d5a0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
2d5b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2d5c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2d5d0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2d5e0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2d5f0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2d600 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2d610 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2d620 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2d630 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2d640 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
2d650 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
2d660 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
2d670 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
2d680 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
2d690 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
2d6a0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
2d6b0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
2d6c0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
2d6d0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
2d6e0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
2d6f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2d700 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2d710 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
2d720 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d730 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
2d740 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2d750 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2d760 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
2d770 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
2d780 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
2d790 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
2d7a0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
2d7b0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2d7c0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
2d7d0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
2d7e0 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
2d7f0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
2d800 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
2d810 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2d820 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2d830 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
2d840 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
2d850 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
2d860 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
2d870 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
2d880 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
2d890 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
2d8a0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
2d8b0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
2d8c0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2d8d0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
2d8e0 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
2d8f0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
2d900 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
2d910 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
2d920 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
2d930 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
2d940 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
2d950 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
2d960 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
2d970 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
2d980 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
2d990 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
2d9a0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
2d9b0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
2d9c0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
2d9d0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
2d9e0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
2d9f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
2da00 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
2da10 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2da20 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2da30 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2da40 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2da50 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2da60 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2da70 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
2da80 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2da90 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2daa0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2dab0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
2dac0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
2dad0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
2dae0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
2daf0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2db00 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
2db10 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
2db20 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2db30 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2db40 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
2db50 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2db60 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
2db70 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
2db80 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
2db90 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
2dba0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
2dbb0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
2dbc0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2dbd0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2dbe0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2dbf0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2dc00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2dc10 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
2dc20 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2dc30 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2dc40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2dc50 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
2dc60 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2dc70 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2dc80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2dc90 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2dca0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2dcb0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2dcc0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
2dcd0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2dce0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2dcf0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2dd00 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
2dd10 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2dd20 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2dd30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2dd40 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
2dd50 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2dd60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2dd70 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
2dd80 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
2dd90 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
2dda0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2ddb0 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
2ddc0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
2ddd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2dde0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
2ddf0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
2de00 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
2de10 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
2de20 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
2de30 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
2de40 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
2de50 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
2de60 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
2de70 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2de80 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
2de90 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
2dea0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
2deb0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
2dec0 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
2ded0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2dee0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
2def0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2df00 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
2df10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2df20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
2df30 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2df40 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
2df50 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
2df60 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2df70 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
2df80 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
2df90 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
2dfa0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
2dfb0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
2dfc0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
2dfd0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
2dfe0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
2dff0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
2e000 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
2e010 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
2e020 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
2e030 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
2e040 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
2e050 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
2e060 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
2e070 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
2e080 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
2e090 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
2e0a0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
2e0b0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
2e0c0 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
2e0d0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
2e0e0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
2e0f0 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
2e100 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
2e110 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
2e120 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
2e130 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
2e140 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
2e150 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
2e160 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
2e170 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
2e180 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
2e190 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
2e1a0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
2e1b0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
2e1c0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
2e1d0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
2e1e0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
2e1f0 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
2e200 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
2e210 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2e220 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
2e230 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2e240 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e250 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2e260 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2e270 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2e280 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
2e290 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
2e2a0 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
2e2b0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e2c0 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2e2d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2e2e0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2e2f0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2e300 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e310 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2e320 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2e330 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2e340 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2e350 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2e360 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2e370 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2e380 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2e390 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2e3a0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2e3b0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2e3c0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2e3d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2e3e0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2e3f0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2e400 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2e410 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2e420 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2e430 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2e440 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2e450 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2e460 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2e470 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2e480 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e490 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2e4a0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2e4b0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2e4c0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2e4d0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2e4e0 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2e4f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2e500 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2e510 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2e520 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2e530 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2e540 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2e550 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2e560 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2e570 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2e580 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2e590 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2e5a0 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2e5b0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2e5c0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2e5d0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2e5e0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2e5f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2e600 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2e610 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2e620 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2e630 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2e640 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2e650 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2e660 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2e670 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2e680 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2e690 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2e6a0 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2e6b0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2e6c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2e6d0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2e6e0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2e6f0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2e700 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2e710 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2e720 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2e730 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2e740 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2e750 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2e760 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2e770 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2e780 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2e790 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2e7a0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2e7b0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2e7c0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2e7d0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2e7e0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2e7f0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2e800 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2e810 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2e820 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2e830 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2e840 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2e850 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2e860 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2e870 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2e880 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2e890 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2e8a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2e8b0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2e8c0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2e8d0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2e8e0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2e8f0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2e900 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2e910 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2e920 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2e930 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2e940 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2e950 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2e960 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2e970 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2e980 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2e990 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2e9a0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2e9b0 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2e9c0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2e9d0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2e9e0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2e9f0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2ea00 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2ea10 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2ea20 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2ea30 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2ea40 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2ea50 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2ea60 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2ea70 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2ea80 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2ea90 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2eaa0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2eab0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2eac0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2ead0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2eae0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2eaf0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2eb00 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2eb10 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2eb20 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2eb30 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2eb40 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2eb50 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2eb60 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2eb70 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2eb80 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2eb90 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2eba0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2ebb0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2ebc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ebd0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2ebe0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2ebf0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2ec00 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2ec10 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2ec20 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2ec30 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2ec40 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2ec50 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2ec60 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2ec70 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2ec80 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2ec90 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2eca0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2ecb0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2ecc0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2ecd0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2ece0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2ecf0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2ed00 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2ed10 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2ed20 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2ed30 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2ed40 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2ed50 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2ed60 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2ed70 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2ed80 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2ed90 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2eda0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2edb0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2edc0 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2edd0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2ede0 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2edf0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2ee00 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2ee10 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2ee20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2ee30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2ee40 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2ee50 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2ee60 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2ee70 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2ee80 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2ee90 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2eea0 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2eeb0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2eec0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2eed0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2eee0 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2eef0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2ef00 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2ef10 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2ef20 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2ef30 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2ef40 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2ef50 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2ef60 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2ef70 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2ef80 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2ef90 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2efa0 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2efb0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2efc0 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2efd0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2efe0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2eff0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2f000 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2f010 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2f020 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2f030 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2f040 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2f050 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2f060 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2f070 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2f080 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2f090 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2f0a0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2f0b0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2f0c0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2f0d0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2f0e0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2f0f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2f100 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2f110 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2f120 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2f130 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2f140 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2f150 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2f160 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2f170 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2f180 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2f190 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2f1a0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2f1b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2f1c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2f1d0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2f1e0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2f1f0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2f200 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2f210 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2f220 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2f230 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2f240 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2f250 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2f260 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2f270 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2f280 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2f290 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2f2a0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2f2b0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2f2c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2f2d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2f2e0 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2f2f0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2f300 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f310 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2f320 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2f330 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2f340 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2f350 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2f360 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2f370 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2f380 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2f390 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2f3a0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2f3b0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2f3c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2f3d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2f3e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f3f0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2f400 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2f410 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
2f420 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2f430 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2f440 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
2f450 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2f460 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2f470 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
2f480 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2f490 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2f4a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f4b0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
2f4c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f4d0 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
2f4e0 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
2f4f0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
2f500 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
2f510 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2f520 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
2f530 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
2f540 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
2f550 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2f560 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
2f570 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f580 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2f590 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
2f5a0 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
2f5b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2f5c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2f5d0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2f5e0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2f5f0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2f600 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2f610 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2f620 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
2f630 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2f640 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
2f650 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
2f660 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
2f670 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
2f680 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2f690 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2f6a0 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
2f6b0 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
2f6c0 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
2f6d0 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
2f6e0 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
2f6f0 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
2f700 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
2f710 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
2f720 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
2f730 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
2f740 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
2f750 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
2f760 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
2f770 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
2f780 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
2f790 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2f7a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2f7b0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
2f7c0 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
2f7d0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
2f7e0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
2f7f0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2f800 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2f810 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2f820 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2f830 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2f840 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2f850 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2f860 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2f870 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2f880 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2f890 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2f8a0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
2f8b0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2f8c0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
2f8d0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
2f8e0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2f8f0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
2f900 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
2f910 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
2f920 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
2f930 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
2f940 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
2f950 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
2f960 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
2f970 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
2f980 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
2f990 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
2f9a0 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
2f9b0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
2f9c0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
2f9d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2f9e0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
2f9f0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
2fa00 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2fa10 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
2fa20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
2fa30 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
2fa40 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
2fa50 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2fa60 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
2fa70 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
2fa80 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
2fa90 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
2faa0 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
2fab0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
2fac0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
2fad0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
2fae0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2faf0 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
2fb00 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2fb10 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2fb20 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2fb30 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2fb40 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2fb50 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2fb60 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2fb70 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2fb80 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2fb90 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2fba0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2fbb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fbc0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2fbd0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2fbe0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2fbf0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2fc00 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
2fc10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2fc20 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
2fc30 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
2fc40 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2fc50 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2fc60 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2fc70 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
2fc80 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
2fc90 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
2fca0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2fcb0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2fcc0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
2fcd0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
2fce0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2fcf0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
2fd00 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
2fd10 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2fd20 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2fd30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2fd40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
2fd50 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
2fd60 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
2fd70 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
2fd80 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
2fd90 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
2fda0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
2fdb0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
2fdc0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
2fdd0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2fde0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
2fdf0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2fe00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2fe10 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
2fe20 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
2fe30 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2fe40 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
2fe50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2fe60 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
2fe70 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
2fe80 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
2fe90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2fea0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
2feb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2fec0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2fed0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2fee0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
2fef0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2ff00 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
2ff10 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2ff20 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
2ff30 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2ff40 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
2ff50 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2ff60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2ff70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2ff80 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
2ff90 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
2ffa0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
2ffb0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
2ffc0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2ffd0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
2ffe0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2fff0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
30000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
30010 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
30020 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
30030 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
30040 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
30050 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
30060 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
30070 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
30080 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
30090 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
300a0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
300b0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
300c0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
300d0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
300e0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
300f0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
30100 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
30110 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
30120 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
30130 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
30140 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
30150 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
30160 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
30170 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
30180 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
30190 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
301a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
301b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
301c0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
301d0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
301e0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
301f0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
30200 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
30210 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
30220 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
30230 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
30240 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
30250 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
30260 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
30270 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
30280 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
30290 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
302a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
302b0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
302c0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
302d0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
302e0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
302f0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
30300 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
30310 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
30320 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
30330 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
30340 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
30350 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
30360 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
30370 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
30380 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30390 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
303a0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
303b0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
303c0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
303d0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
303e0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
303f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
30400 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
30410 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
30420 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
30430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30440 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
30450 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
30460 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
30470 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
30480 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
30490 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
304a0 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
304b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
304c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
304d0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
304e0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
304f0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
30500 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
30510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30520 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
30530 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
30540 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
30550 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
30560 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
30570 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
30580 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
30590 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
305a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
305b0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
305c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
305d0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
305e0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
305f0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
30600 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
30610 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
30620 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
30630 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
30640 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
30650 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30660 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
30670 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
30680 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
30690 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
306a0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
306b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
306c0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
306d0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
306e0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
306f0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
30700 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
30710 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
30720 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
30730 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
30740 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
30750 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
30760 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
30770 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
30780 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
30790 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
307a0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
307b0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
307c0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
307d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
307e0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
307f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30800 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
30810 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
30820 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
30830 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
30840 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
30850 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
30860 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
30870 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
30880 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
30890 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69  ..**.** <b>Warni
308a0 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a  ng:</b> ^The obj
308b0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
308c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
308d0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
308e0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
308f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30900 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74  ject.  In a mult
30910 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f  ithreaded enviro
30920 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70  nment,.** an unp
30930 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30940 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
30950 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73  y only be used s
30960 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73  afely with.** [s
30970 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
30980 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
30990 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
309a0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
309b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
309c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
309d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
309e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
309f0 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
30a00 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
30a10 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
30a20 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
30a30 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
30a40 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
30a50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30a60 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
30a70 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
30a80 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  )], the behavior
30a90 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
30aa0 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  fe..**.** These 
30ab0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
30ac0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
30ad0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
30ae0 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
30af0 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
30b00 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
30b10 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
30b20 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
30b30 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
30b40 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
30b50 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
30b60 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
30b70 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
30b80 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
30b90 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
30ba0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
30bb0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
30bc0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
30bd0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
30be0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
30bf0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
30c00 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
30c10 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
30c20 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
30c30 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
30c40 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
30c50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
30c60 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
30c70 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
30c80 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
30c90 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
30ca0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
30cb0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
30cc0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
30cd0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
30ce0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
30cf0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
30d00 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
30d10 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
30d20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
30d30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
30d40 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
30d50 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
30d60 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
30d70 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
30d80 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
30d90 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
30da0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
30db0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
30dc0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
30dd0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
30de0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
30df0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
30e00 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
30e10 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
30e20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30e30 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
30e40 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
30e50 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
30e60 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
30e70 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
30e80 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
30e90 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
30ea0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
30eb0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
30ec0 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
30ed0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
30ee0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
30ef0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
30f00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
30f10 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
30f20 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
30f30 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
30f40 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
30f50 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
30f60 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
30f70 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
30f80 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
30f90 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
30fa0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
30fb0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
30fc0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
30fd0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
30fe0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
30ff0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
31000 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
31010 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
31020 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
31030 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
31040 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ote>)^.**.** Not
31050 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
31060 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
31070 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
31080 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
31090 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
310a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
310b0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
310c0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
310d0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
310e0 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
310f0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
31100 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
31110 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
31120 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
31130 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
31140 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
31150 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
31160 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
31170 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
31180 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
31190 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
311a0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
311b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
311c0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
311d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
311e0 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
311f0 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
31200 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
31210 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
31220 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
31230 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
31240 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31250 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
31260 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
31270 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
31280 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
31290 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
312a0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
312b0 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
312c0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
312d0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
312e0 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
312f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31300 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
31310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31320 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
31330 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
31340 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
31350 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
31360 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
31370 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
31380 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
31390 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
313a0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
313b0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
313c0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
313d0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
313e0 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
313f0 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
31400 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
31410 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
31420 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
31430 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
31440 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
31450 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
31460 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
31470 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
31480 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
31490 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
314a0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
314b0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
314c0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
314d0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
314e0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
314f0 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c  * The safest pol
31500 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
31510 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
31520 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
31530 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
31540 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
31550 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
31560 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
31570 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
31580 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
31590 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
315a0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
315b0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
315c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
315d0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
315e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
315f0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
31600 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
31610 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
31620 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
31630 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
31640 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
31650 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31660 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
31670 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
31680 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
31690 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
316a0 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
316b0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
316c0 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
316d0 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
316e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
316f0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
31700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31710 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
31720 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
31730 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
31740 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
31750 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31760 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
31770 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
31780 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
31790 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
317a0 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
317b0 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
317c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
317d0 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
317e0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
317f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
31800 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
31810 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
31820 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
31830 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
31840 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
31850 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
31860 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
31870 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
31880 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
31890 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
318a0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
318b0 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
318c0 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
318d0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
318e0 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
318f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
31900 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  Do <em>not</em> 
31910 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
31920 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
31930 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
31940 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
31950 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31960 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
31970 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
31980 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
31990 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
319a0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
319b0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
319c0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
319d0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
319e0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
319f0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
31a00 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
31a10 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
31a20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
31a30 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
31a40 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
31a50 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
31a60 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
31a70 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
31a80 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
31a90 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
31aa0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
31ab0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
31ac0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
31ad0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31ae0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
31af0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31b00 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
31b10 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
31b20 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
31b30 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
31b40 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31b50 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
31b60 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
31b70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31b80 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
31b90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
31ba0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31bb0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
31bc0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
31bd0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
31be0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31bf0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
31c00 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
31c10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31c20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31c30 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
31c40 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
31c50 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
31c60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31c70 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
31c80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
31c90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31ca0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
31cb0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
31cc0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
31cd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31ce0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
31cf0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
31d00 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
31d10 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
31d20 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
31d30 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
31d40 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
31d50 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
31d60 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
31d70 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
31d80 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
31d90 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
31da0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
31db0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
31dc0 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
31dd0 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
31de0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
31df0 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
31e00 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
31e10 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
31e20 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
31e30 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
31e40 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
31e50 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
31e60 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
31e70 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
31e80 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
31e90 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
31ea0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
31eb0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
31ec0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
31ed0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
31ee0 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
31ef0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
31f00 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
31f10 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
31f20 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
31f30 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
31f40 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
31f50 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
31f60 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
31f70 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
31f80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
31f90 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
31fa0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
31fb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31fc0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
31fd0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
31fe0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
31ff0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
32000 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
32010 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
32020 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
32030 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
32040 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
32050 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
32060 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
32070 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
32080 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
32090 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
320a0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
320b0 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
320c0 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
320d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
320e0 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
320f0 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
32100 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
32110 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
32120 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
32130 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
32140 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
32150 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
32160 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
32170 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
32180 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
32190 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
321a0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
321b0 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
321c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
321d0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
321e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
321f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
32200 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
32210 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
32220 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
32230 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68  e3_stmt.**.** Th
32240 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
32250 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
32260 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
32270 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32280 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
32290 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
322a0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
322b0 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
322c0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
322d0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
322e0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
322f0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
32300 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
32310 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
32320 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
32330 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
32340 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
32350 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
32360 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
32370 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
32380 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
32390 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
323a0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
323b0 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
323c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
323d0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
323e0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
323f0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
32400 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
32410 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
32420 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
32430 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
32440 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
32450 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
32460 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
32470 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
32480 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
32490 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
324a0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
324b0 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
324c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
324d0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
324e0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
324f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
32500 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
32510 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
32520 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
32530 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
32540 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
32550 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
32560 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
32570 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
32580 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
32590 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
325a0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
325b0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
325c0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
325d0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
325e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
325f0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
32600 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32610 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
32620 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
32630 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
32640 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
32650 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
32660 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
32670 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
32680 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
32690 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
326a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
326b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
326c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
326d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
326e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
326f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
32700 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32710 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
32720 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
32730 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
32740 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
32750 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
32760 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
32770 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
32780 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
32790 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
327a0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
327b0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
327c0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
327d0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
327e0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
327f0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
32800 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
32810 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
32820 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
32830 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
32840 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
32850 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
32860 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
32870 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
32880 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
32890 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
328a0 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
328b0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
328c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
328d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
328e0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
328f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32900 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
32910 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
32920 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
32930 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
32940 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
32950 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
32960 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
32970 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32980 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
32990 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
329a0 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
329b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
329c0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
329d0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
329e0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
329f0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
32a00 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
32a10 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
32a20 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
32a30 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
32a40 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
32a50 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
32a60 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
32a70 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
32a80 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
32a90 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
32aa0 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
32ab0 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
32ac0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
32ad0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
32ae0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
32af0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
32b00 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
32b10 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
32b20 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
32b30 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
32b40 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
32b50 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
32b60 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
32b70 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
32b80 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
32b90 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
32ba0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32bb0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
32bc0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
32bd0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
32be0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
32bf0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
32c00 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
32c10 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
32c20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
32c30 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
32c40 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
32c50 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
32c60 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
32c70 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
32c80 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
32c90 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
32ca0 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
32cb0 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
32cc0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
32cd0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
32ce0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
32cf0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
32d00 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
32d10 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
32d20 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
32d30 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
32d40 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
32d50 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
32d60 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
32d70 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
32d80 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
32d90 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
32da0 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
32db0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
32dc0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
32dd0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32de0 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
32df0 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
32e00 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
32e10 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
32e20 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
32e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32e40 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
32e50 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
32e60 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
32e70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32e80 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
32e90 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
32ea0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
32eb0 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
32ec0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
32ed0 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
32ee0 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
32ef0 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
32f00 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
32f10 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
32f20 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
32f30 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
32f40 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
32f50 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
32f60 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
32f70 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
32f80 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
32f90 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
32fa0 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
32fb0 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
32fc0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
32fd0 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
32fe0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
32ff0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
33000 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
33010 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
33020 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
33030 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
33040 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
33050 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
33060 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
33070 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
33080 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
33090 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
330a0 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
330b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
330c0 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
330d0 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
330e0 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
330f0 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
33100 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
33110 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
33120 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
33130 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
33140 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
33150 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
33160 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
33170 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
33180 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
33190 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
331a0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
331b0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
331c0 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
331d0 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
331e0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
331f0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
33200 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
33210 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
33220 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
33230 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
33240 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
33250 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
33260 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
33270 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
33280 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
33290 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
332a0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
332b0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
332c0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
332d0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
332e0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
332f0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
33300 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
33310 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
33320 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
33330 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
33340 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
33350 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
33360 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
33370 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
33380 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
33390 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
333a0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
333b0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
333c0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
333d0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
333e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
333f0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
33400 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
33410 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
33420 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
33430 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
33440 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
33450 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
33460 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
33470 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
33480 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
33490 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
334a0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
334b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
334c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
334d0 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
334e0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
334f0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
33500 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
33510 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
33520 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
33530 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
33540 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
33550 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
33560 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
33570 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
33580 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
33590 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
335a0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
335b0 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
335c0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
335d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
335e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
335f0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
33600 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
33610 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
33620 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
33630 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
33640 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
33650 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
33660 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
33670 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
33680 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
33690 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
336a0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
336b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
336c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
336d0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
336e0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
336f0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
33700 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
33710 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
33720 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
33730 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
33740 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
33750 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
33760 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
33770 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
33780 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
33790 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
337a0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
337b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
337c0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
337d0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
337e0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
337f0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
33800 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
33810 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
33820 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
33830 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
33840 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
33850 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
33860 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
33870 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
33880 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
33890 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
338a0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
338b0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
338c0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
338d0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
338e0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
338f0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
33900 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
33910 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
33920 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
33930 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
33940 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
33950 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
33960 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
33970 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
33980 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
33990 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
339a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
339b0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
339c0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
339d0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
339e0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
339f0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
33a00 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
33a10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33a20 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
33a30 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
33a40 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33a50 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
33a60 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
33a70 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
33a80 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
33a90 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
33aa0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
33ab0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33ac0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
33ad0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
33ae0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
33af0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
33b00 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
33b10 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
33b20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33b30 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
33b40 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
33b50 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
33b60 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
33b70 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
33b80 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
33b90 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
33ba0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33bb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33bc0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
33bd0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
33be0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
33bf0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
33c00 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
33c10 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
33c20 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
33c30 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
33c40 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
33c50 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
33c60 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
33c70 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
33c80 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
33c90 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
33ca0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
33cb0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
33cc0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
33cd0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
33ce0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33d00 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
33d10 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
33d20 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
33d30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33d40 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
33d50 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
33d60 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
33d70 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
33d80 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
33d90 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
33da0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
33db0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33dc0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33dd0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
33de0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
33df0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
33e00 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
33e10 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
33e20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
33e30 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
33e40 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
33e50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
33e60 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
33e70 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
33e80 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
33e90 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
33ea0 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
33eb0 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
33ec0 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
33ed0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
33ee0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
33ef0 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a           1    /*
33f00 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35   IMP: R-37514-35
33f10 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  566 */.#define S
33f20 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
33f30 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50       2    /* IMP
33f40 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20  : R-03371-37637 
33f50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
33f60 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
33f70 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   3    /* IMP: R-
33f80 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23  51971-34154 */.#
33f90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
33fa0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
33fb0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
33fc0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
33fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
33fe0 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
33ff0 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a   /* Deprecated *
34000 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
34010 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
34020 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
34030 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34040 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
34050 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
34060 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54  on Flags.**.** T
34070 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d  hese constants m
34080 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74  ay be ORed toget
34090 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  her with the .**
340a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
340b0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
340c0 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20  ncoding] as the 
340d0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a  fourth argument.
340e0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
340f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
34100 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
34110 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
34120 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
34130 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
34140 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _v2()]..*/.#defi
34150 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  ne SQLITE_DETERM
34160 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30  INISTIC    0x800
34170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34180 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
34190 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
341a0 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
341b0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
341c0 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
341d0 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
341e0 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
341f0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
34200 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
34210 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
34220 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
34230 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
34240 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
34250 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
34260 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
34270 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
34280 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67  ns.  To encourag
34290 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f  e programmers to
342a0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20   avoid.** these 
342b0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69  functions, we wi
342c0 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77  ll not explain w
342d0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
342e0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
342f0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
34300 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
34310 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
34320 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
34330 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
34340 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
34350 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
34360 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
34370 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
34380 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
34390 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
343a0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
343b0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
343c0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
343d0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
343e0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
343f0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
34400 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
34410 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
34420 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
34430 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
34440 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
34450 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
34460 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
34470 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
34480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34490 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
344a0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
344b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
344c0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c  btaining SQL Val
344d0 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
344e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
344f0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
34500 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
34510 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
34520 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
34530 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
34540 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
34550 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
34560 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
34570 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
34580 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
34590 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20  regate.  .**.** 
345a0 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
345b0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
345c0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
345d0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
345e0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
345f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34600 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
34610 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34620 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
34630 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
34640 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
34650 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
34660 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
34670 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
34680 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
34690 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
346a0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
346b0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
346c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
346d0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
346e0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
346f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
34700 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
34710 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
34720 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
34730 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
34740 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
34750 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
34760 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34770 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
34780 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
34790 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
347a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
347b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
347c0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
347d0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
347e0 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
347f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34800 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
34810 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
34820 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
34830 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
34840 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
34850 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
34860 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
34870 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
34880 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74  ** except that t
34890 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
348a0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
348b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
348c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
348d0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
348e0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
348f0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
34900 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
34910 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
34920 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
34930 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
34940 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
34950 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
34960 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
34970 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
34980 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
34990 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
349a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
349b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
349c0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
349d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
349e0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
349f0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
34a00 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
34a10 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
34a20 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
34a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
34a40 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
34a50 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
34a60 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
34a70 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
34a80 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
34a90 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
34aa0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
34ab0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
34ac0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
34ad0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
34ae0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
34af0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
34b00 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
34b10 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
34b20 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
34b30 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
34b40 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
34b50 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
34b60 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
34b70 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
34b80 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
34b90 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
34ba0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
34bb0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
34bc0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
34bd0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
34be0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
34bf0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
34c00 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
34c10 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
34c20 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
34c30 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
34c40 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
34c50 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
34c60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
34c70 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
34c80 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
34c90 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
34ca0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
34cb0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
34cc0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
34cd0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
34ce0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
34cf0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
34d00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34d10 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
34d20 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34d30 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
34d40 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
34d50 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
34d60 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
34d70 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
34d80 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
34d90 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
34da0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
34db0 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
34dc0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
34dd0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
34de0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
34df0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
34e00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34e10 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
34e20 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
34e30 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
34e40 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
34e50 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
34e60 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
34e70 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
34e80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
34e90 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
34ea0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
34eb0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34ec0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
34ed0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
34ee0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
34ef0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
34f00 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
34f10 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
34f20 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
34f30 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
34f40 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
34f50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34f60 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
34f70 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34f80 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
34f90 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
34fa0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
34fb0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
34fc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
34fd0 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
34fe0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
34ff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
35000 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79 70  nding The Subtyp
35010 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a  e Of SQL Values.
35020 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
35030 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54  e3_value.**.** T
35040 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
35050 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e 63  _subtype(V) func
35060 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
35070 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20   subtype for.** 
35080 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  an [application-
35090 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
350a0 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56  tion] argument V
350b0 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a  .  The subtype.*
350c0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61  * information ca
350d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61 73  n be used to pas
350e0 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75  s a limited amou
350f0 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72  nt of context fr
35100 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75  om.** one SQL fu
35110 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65  nction to anothe
35120 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c  r.  Use the [sql
35130 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74  ite3_result_subt
35140 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  ype()].** routin
35150 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75 62  e to set the sub
35160 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65 74  type for the ret
35170 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  urn value of an 
35180 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
35190 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
351a0 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79   no use of subty
351b0 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d  pe itself.  It m
351c0 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68 65  erely passes the
351d0 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d   subtype.** from
351e0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f   the result of o
351f0 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ne [application-
35200 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
35210 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a  tion] into the.*
35220 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68  * input of anoth
35230 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20  er..*/.unsigned 
35240 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
35250 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65  e_subtype(sqlite
35260 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
35270 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79  * CAPI3REF: Copy
35280 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61   And Free SQL Va
35290 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
352a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
352b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
352c0 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e  _value_dup(V) in
352d0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
352e0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
352f0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
35300 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75  bject D and retu
35310 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
35320 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68   that copy.  ^Th
35330 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
35340 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  ] returned.** is
35350 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   a [protected sq
35360 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
35370 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20  ect even if the 
35380 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a  input is not..**
35390 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
353a0 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
353b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
353c0 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f  L if V is NULL o
353d0 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79  r if a.** memory
353e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
353f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
35400 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
35410 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72  (V) interface fr
35420 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  ees an [sqlite3_
35430 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
35440 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
35450 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
35460 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e  e3_value_dup()].
35470 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c    ^If V is a NUL
35480 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  L pointer.** the
35490 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  n sqlite3_value_
354a0 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72  free(V) is a har
354b0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
354c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
354d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
354e0 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76  (const sqlite3_v
354f0 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
35500 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
35510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
35520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35530 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
35540 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
35550 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ext.** METHOD: s
35560 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
35570 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
35580 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
35590 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
355a0 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
355b0 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
355c0 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
355d0 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
355e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
355f0 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
35600 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35610 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
35620 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
35630 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
35640 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
35650 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
35660 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
35670 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
35680 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
35690 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
356a0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
356b0 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
356c0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
356d0 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
356e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
356f0 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
35700 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
35710 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
35720 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
35730 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
35740 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
35750 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
35760 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
35770 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
35780 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
35790 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
357a0 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
357b0 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
357c0 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
357d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
357e0 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
357f0 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
35800 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
35810 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
35820 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
35830 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
35840 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
35850 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
35860 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
35870 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
35880 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
35890 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
358a0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
358b0 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
358c0 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
358d0 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
358e0 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
358f0 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
35900 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
35910 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
35920 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35930 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a  a NULL pointer .
35940 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61  ** when first ca
35950 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73  lled if N is les
35960 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
35970 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
35980 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
35990 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
359a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
359b0 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
359c0 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
359d0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
359e0 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
359f0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
35a00 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
35a10 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
35a20 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
35a30 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
35a40 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
35a50 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
35a60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
35a70 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
35a80 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
35a90 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
35aa0 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
35ab0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
35ac0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20  * allocation.)^ 
35ad0 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e   Within the xFin
35ae0 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20  al callback, it 
35af0 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20  is customary to 
35b00 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61  set.** N=0 in ca
35b10 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
35b20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
35b30 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f  (C,N) so that no
35b40 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d   .** pointless m
35b50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
35b60 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e  s occur..**.** ^
35b70 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
35b80 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
35b90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
35ba0 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
35bb0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
35bc0 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
35bd0 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
35be0 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
35bf0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
35c00 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
35c10 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
35c20 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
35c30 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
35c40 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
35c50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
35c60 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
35c70 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
35c80 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
35c90 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
35ca0 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
35cb0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
35cc0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
35cd0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
35ce0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
35cf0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
35d00 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
35d10 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
35d20 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
35d30 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
35d40 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
35d50 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
35d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35d70 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
35d80 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
35d90 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
35da0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  text.**.** ^The 
35db0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
35dc0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
35dd0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
35de0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
35df0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
35e00 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
35e10 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
35e20 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
35e30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35e40 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
35e50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35e60 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
35e70 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
35e80 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
35e90 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
35ea0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
35eb0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
35ec0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
35ed0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
35ee0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
35ef0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
35f00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35f10 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
35f20 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
35f30 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
35f40 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
35f50 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
35f60 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
35f70 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
35f80 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
35f90 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
35fa0 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ext.**.** ^The s
35fb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
35fc0 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
35fd0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
35fe0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
35ff0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
36000 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36010 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
36020 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
36030 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36040 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
36050 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
36060 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
36070 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
36080 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
36090 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
360a0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
360b0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
360c0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
360d0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
360e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
360f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36100 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
36110 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 20  xiliary Data.** 
36120 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
36130 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68  context.**.** Th
36140 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  ese functions ma
36150 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f  y be used by (no
36160 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c  n-aggregate) SQL
36170 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
36180 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
36190 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
361a0 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
361b0 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
361c0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
361d0 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
361e0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
361f0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
36200 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
36210 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
36220 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
36230 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
36240 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
36250 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d  served.  An exam
36260 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20  ple.** of where 
36270 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73  this might be us
36280 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67  eful is in a reg
36290 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
362a0 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63  matching.** func
362b0 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
362c0 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
362d0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
362e0 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72  sion can be stor
362f0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
36300 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
36310 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  h the pattern st
36320 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20  ring.  .** Then 
36330 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70  as long as the p
36340 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65  attern string re
36350 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a  mains the same,.
36360 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  ** the compiled 
36370 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
36380 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
36390 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
363a0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
363b0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
363c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
363d0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
363e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
363f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
36400 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
36410 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
36420 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
36430 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
36440 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
36450 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
36460 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
36470 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36480 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65  ction. ^If there
36490 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a   is no metadata.
364a0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
364b0 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  th the function 
364c0 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73  argument, this s
364d0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
364e0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ta() interface.*
364f0 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
36500 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
36510 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
36520 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
36530 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
36540 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20  s P as metadata 
36550 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
36560 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
36570 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36580 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  ned function.  ^
36590 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
365a0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
365b0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20  et_auxdata(C,N) 
365c0 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68  return P from th
365d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
365e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
365f0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61  data(C,N,P,X) ca
36600 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61  ll if the metada
36610 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69  ta is still vali
36620 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20  d or.** NULL if 
36630 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73  the metadata has
36640 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e   been discarded.
36650 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20  .** ^After each 
36660 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
36670 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
36680 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20  P,X) where X is 
36690 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c  not NULL,.** SQL
366a0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
366b0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  the destructor f
366c0 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70  unction X with p
366d0 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74  arameter P exact
366e0 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e  ly.** once, when
366f0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
36700 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53   discarded..** S
36710 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
36720 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74   discard the met
36730 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d  adata at any tim
36740 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75  e, including: <u
36750 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  l>.** <li> when 
36760 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
36770 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
36780 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72  eter changes, or
36790 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73  .** <li> when [s
367a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
367b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
367c0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
367d0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  d for the.**    
367e0 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c    SQL statement,
367f0 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
36800 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
36810 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65  data() is invoke
36820 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73  d again on the s
36830 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  ame parameter, o
36840 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67  r.** <li> during
36850 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71   the original sq
36860 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
36870 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20  a() call when a 
36880 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20  memory .**      
36890 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
368a0 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e   occurs. </ul>)^
368b0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20  .**.** Note the 
368c0 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70  last bullet in p
368d0 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20  articular.  The 
368e0 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20  destructor X in 
368f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
36900 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
36910 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
36920 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
36930 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69  fore the.** sqli
36940 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
36950 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e  ) interface even
36960 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65   returns.  Hence
36970 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
36980 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64  data().** should
36990 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20   be called near 
369a0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
369b0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
369c0 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a  tation and the.*
369d0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  * function imple
369e0 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
369f0 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73   not make any us
36a00 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20  e of P after.** 
36a10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
36a20 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63  ata() has been c
36a30 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  alled..**.** ^(I
36a40 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
36a50 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
36a60 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
36a70 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
36a80 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
36a90 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d  ers that are com
36aa0 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61  pile-time consta
36ab0 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c  nts, including l
36ac0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
36ad0 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
36ae0 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e  ] and expression
36af0 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20  s composed from 
36b00 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a  the same.)^.**.*
36b10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
36b20 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
36b30 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
36b40 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
36b50 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
36b60 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
36b70 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
36b80 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
36b90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
36ba0 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
36bb0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
36bc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36bd0 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
36be0 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
36bf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36c00 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
36c10 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
36c20 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
36c30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
36c40 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
36c50 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
36c60 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
36c70 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
36c80 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
36c90 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
36ca0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36cb0 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
36cc0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
36cd0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
36ce0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
36cf0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
36d00 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
36d10 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
36d20 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
36d30 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
36d40 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
36d50 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
36d60 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
36d70 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
36d80 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
36d90 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
36da0 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
36db0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
36dc0 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
36dd0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
36de0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
36df0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
36e00 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
36e10 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
36e20 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
36e30 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
36e40 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
36e50 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f  ++ compilers..*/
36e60 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
36e70 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
36e80 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
36e90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36ea0 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
36eb0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
36ec0 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
36ed0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
36ee0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
36ef0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
36f00 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
36f10 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
36f20 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
36f30 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48  Function.** METH
36f40 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
36f50 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ext.**.** These 
36f60 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
36f70 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
36f80 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
36f90 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
36fa0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
36fb0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
36fc0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
36fd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
36fe0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
36ff0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
37000 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
37010 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
37020 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
37030 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
37040 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
37050 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
37060 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
37070 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
37080 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
37090 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
370a0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
370b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
370c0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
370d0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
370e0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
370f0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
37100 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
37110 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37120 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
37130 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
37140 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
37150 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37160 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
37170 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
37180 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
37190 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
371a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
371b0 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
371c0 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
371d0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
371e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
371f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37200 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
37210 6f 62 28 43 2c 4e 29 20 61 6e 64 20 73 71 6c 69  ob(C,N) and sqli
37220 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
37230 6c 6f 62 36 34 28 43 2c 4e 29 0a 2a 2a 20 69 6e  lob64(C,N).** in
37240 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
37250 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 61   result of the a
37260 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37270 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
37280 65 0a 2a 2a 20 61 20 42 4c 4f 42 20 63 6f 6e 74  e.** a BLOB cont
37290 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 20  aining all zero 
372a0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
372b0 73 20 69 6e 20 73 69 7a 65 2e 0a 2a 2a 0a 2a 2a  s in size..**.**
372c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
372d0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
372e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
372f0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
37300 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
37310 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37320 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
37330 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
37340 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
37350 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
37360 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37370 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
37380 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
37390 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
373a0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
373b0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
373c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
373d0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
373e0 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
373f0 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
37400 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
37410 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
37420 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
37430 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
37440 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37450 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
37460 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
37470 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
37480 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
37490 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
374a0 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
374b0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
374c0 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
374d0 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
374e0 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
374f0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
37500 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37510 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
37520 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
37530 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
37540 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
37550 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37560 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
37570 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37580 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
37590 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
375a0 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
375b0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
375c0 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
375d0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
375e0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
375f0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
37600 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
37610 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
37620 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
37630 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
37640 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
37650 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
37660 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
37670 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
37680 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
37690 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
376a0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
376b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
376c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
376d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
376e0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
376f0 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
37700 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
37710 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
37720 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
37730 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
37740 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
37750 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
37760 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
37770 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
37780 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
37790 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
377a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
377b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
377c0 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
377d0 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
377e0 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
377f0 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
37800 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
37810 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
37820 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
37830 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
37840 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
37850 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
37860 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
37870 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
37880 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
37890 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
378a0 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
378b0 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
378c0 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
378d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
378e0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20  _error_toobig() 
378f0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
37900 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
37910 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
37920 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
37930 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
37940 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
37950 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
37960 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37970 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20  t_error_nomem() 
37980 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
37990 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
379a0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
379b0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
379c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
379d0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
379e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
379f0 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
37a00 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
37a10 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
37a20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37a30 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37a40 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
37a50 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
37a60 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
37a70 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
37a80 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
37a90 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
37aa0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
37ab0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
37ac0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
37ad0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37ae0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
37af0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
37b00 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
37b10 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
37b20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
37b30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37b40 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
37b50 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
37b60 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
37b70 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
37b80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37b90 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
37ba0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37bb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37bc0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
37bd0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
37be0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37bf0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
37c00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37c10 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
37c20 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
37c30 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
37c40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37c50 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37c60 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
37c70 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
37c80 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
37c90 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
37ca0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
37cb0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
37cc0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
37cd0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
37ce0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
37cf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37d00 75 6c 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74  ult_text64() int
37d10 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
37d20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
37d30 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  an.** applicatio
37d40 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
37d50 6f 6e 20 74 6f 20 62 65 20 61 20 74 65 78 74 20  on to be a text 
37d60 73 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63  string in an enc
37d70 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69  oding.** specifi
37d80 65 64 20 62 79 20 74 68 65 20 66 69 66 74 68 20  ed by the fifth 
37d90 28 61 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d  (and last) param
37da0 65 74 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74  eter, which must
37db0 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53   be one.** of [S
37dc0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
37dd0 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
37de0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
37df0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
37e00 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  E]..** ^SQLite t
37e10 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
37e20 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
37e30 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
37e40 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
37e50 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
37e60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
37e70 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
37e80 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
37e90 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
37ea0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
37eb0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
37ec0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
37ed0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
37ee0 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
37ef0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
37f00 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
37f10 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
37f20 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
37f30 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
37f40 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
37f50 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
37f60 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
37f70 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
37f80 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
37f90 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
37fa0 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
37fb0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
37fc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
37fd0 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
37fe0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37ff0 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
38000 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72  sult.  If the 3r
38010 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
38020 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
38030 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20  n it.** must be 
38040 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20  the byte offset 
38050 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20  into the string 
38060 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
38070 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a  rminator would.*
38080 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20  * appear if the 
38090 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c  string where NUL
380a0 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
380b0 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
380c0 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ers occur.** in 
380d0 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20  the string at a 
380e0 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74  byte offset that
380f0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68   is less than th
38100 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33  e value of the 3
38110 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  rd.** parameter,
38120 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
38130 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  ing string will 
38140 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
38150 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a   NULs and the.**
38160 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
38170 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67  ssions operating
38180 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68   on strings with
38190 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
381a0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
381b0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
381c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
381d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
381e0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
381f0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
38200 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
38210 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
38220 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
38230 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
38240 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
38250 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
38260 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
38270 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
38280 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
38290 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
382a0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
382b0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
382c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
382d0 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
382e0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
382f0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
38300 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
38310 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
38320 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
38330 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
38340 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
38350 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
38360 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
38370 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
38380 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
38390 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
383a0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
383b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
383c0 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
383d0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
383e0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
383f0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
38400 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
38410 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
38420 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
38430 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
38440 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
38450 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
38460 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
38470 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
38480 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
38490 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
384a0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
384b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
384c0 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
384d0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
384e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
384f0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
38500 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
38510 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
38520 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
38530 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
38540 6f 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  o be a copy of t
38550 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
38560 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
38570 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
38580 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
38590 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
385a0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
385b0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
385c0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
385d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
385e0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
385f0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
38600 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
38610 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
38620 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
38630 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
38640 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
38650 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
38660 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
38670 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
38680 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
38690 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
386a0 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
386b0 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
386c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
386d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
386e0 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
386f0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
38700 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
38710 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
38720 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
38730 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
38740 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
38750 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
38760 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
38770 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
38780 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
38790 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
387a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
387b0 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
387c0 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
387d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
387e0 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
387f0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
38800 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
38810 33 5f 72 65 73 75