/ Hex Artifact Content
Login

Artifact cc65ace88ea9f6eefceeeb680407b7544fea8535:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  eter of.** sqlit
39c0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
39d0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
39e0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
39f0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3a00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3a10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3a30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3a40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3a50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3a60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3a70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3a80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3a90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3aa0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3ab0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3ac0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3ad0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3af0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3b00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3b10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3b20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3b30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3b40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3b50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3b60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3b70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3b80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3b90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3ba0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3bb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3bc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3bd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3be0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3bf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3c10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3c20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3c30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3c40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3c50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3c60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3c70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3c80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3c90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3ca0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3cb0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3cc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3cd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3ce0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3cf0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3d20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3d50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3d60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3d70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3d80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3d90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3da0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3db0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3dc0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3dd0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3de0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3df0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3e00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3e10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3e20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3e30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3e40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3e50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3e60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3e70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3e80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3e90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3ea0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3eb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3ec0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ed0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3ee0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
3ef0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
3f00: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3f10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3f20: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
3f30: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
3f40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
3f50: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3f60: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
3f70: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
3f80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3f90: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3fa0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3fb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3fc0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3fd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fe0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ff0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4000: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4010: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4020: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4030: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4040: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4050: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4060: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4070: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
4080: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
4090: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
40a0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
40d0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
40e0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
40f0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4120: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4130: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4140: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4150: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4160: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4170: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41a0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
41b0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
41c0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
41f0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4200: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4210: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4220: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4230: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4240: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4250: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4260: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4270: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
4280: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
4290: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
42a0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
42b0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
42c0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
42d0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
42e0: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
42f0: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4300: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4310: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4320: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4330: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4340: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4350: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4360: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4370: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4380: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4390: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43a0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
43b0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
43c0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
43d0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
43e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
43f0: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4400: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4410: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4420: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4430: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4440: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4450: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4470: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4480: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4490: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44a0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
44b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
44c0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
44d0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
44e0: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
44f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4500: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4510: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4520: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4530: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4540: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4550: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4560: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4580: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4590: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45a0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
45b0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
45c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
45d0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
45e0: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
45f0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4600: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4620: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4630: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4640: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4650: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4660: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4670: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4680: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4690: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46b0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
46c0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
46d0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
46e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
46f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4700: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4710: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4720: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4730: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4760: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4770: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4780: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4790: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47a0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
47b0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
47c0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
47d0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
47e0: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
47f0: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4810: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4820: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4830: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4840: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4850: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4860: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4870: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4880: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48a0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
48b0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
48c0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
48d0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
48e0: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
48f0: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4900: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4920: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4930: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4940: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4960: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4970: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4980: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4990: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
49b0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
49c0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
49d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
49e0: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
49f0: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a00: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a10: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a20: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a30: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a40: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4a50: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4a60: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a70: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a80: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a90: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4aa0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4ab0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4ad0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4ae0: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4af0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b10: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4b20: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4b30: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b50: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4b60: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4b70: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4b80: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4ba0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4bb0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4bc0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4bd0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4be0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4bf0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4c00: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4c10: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4c20: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4c30: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4c40: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4c50: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4c60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4c70: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4c80: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4c90: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4ca0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4cb0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4cc0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4cd0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4ce0: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4cf0: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4d00: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4d10: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4d20: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4d30: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4d40: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4d50: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4d60: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4d70: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4d80: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4d90: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4da0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
4db0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
4dc0: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
4dd0: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
4de0: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
4df0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
4e00: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
4e10: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
4e20: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
4e30: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
4e40: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4e50: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
4e60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4e70: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
4e80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4e90: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4ea0: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
4eb0: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
4ec0: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
4ed0: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
4ee0: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
4ef0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
4f00: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
4f10: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
4f20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4f30: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f50: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4f60: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4f70: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4f90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fa0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
4fb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
4fd0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4fe0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
4ff0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5000: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5010: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5020: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5030: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5040: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5050: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5060: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
5070: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5080: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
5090: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50a0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
50b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50c0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
50d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50e0: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
50f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5100: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5120: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5130: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5140: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5160: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
5170: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5180: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
5190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51a0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
51b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51c0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5220: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5230: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5240: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5260: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
5270: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
5280: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
5290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52a0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
52b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52c0: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
52d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52e0: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
52f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5300: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5320: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5330: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5340: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
5350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5360: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
5370: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5380: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
5390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53a0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
53b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53c0: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
53d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53e0: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
53f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5400: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5420: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5430: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5440: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
5450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5460: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
5470: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5480: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
5490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54a0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
54b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54c0: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
54d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54e0: 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20  ERR_MMAP        
54f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5500: 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23  ERR | (24<<8)).#
5510: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5520: 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20  ERR_GETTEMPPATH 
5530: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5540: 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23  ERR | (25<<8)).#
5550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5560: 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  ERR_CONVPATH    
5570: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5580: 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23  ERR | (26<<8)).#
5590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55a0: 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20  ERR_VNODE       
55b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
55c0: 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23  ERR | (27<<8)).#
55d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55e0: 45 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20  ERR_AUTH        
55f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5600: 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23  ERR | (28<<8)).#
5610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5620: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5630: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5640: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
5650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5660: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
5670: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5680: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
5690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56a0: 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20  BUSY_SNAPSHOT   
56b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56c0: 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29  BUSY   |  (2<<8)
56d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56e0: 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50  _CANTOPEN_NOTEMP
56f0: 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45  DIR      (SQLITE
5700: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c  _CANTOPEN | (1<<
5710: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5720: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49  TE_CANTOPEN_ISDI
5730: 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  R          (SQLI
5740: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32  TE_CANTOPEN | (2
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5760: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55  LITE_CANTOPEN_FU
5770: 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51  LLPATH       (SQ
5780: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5790: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
57a0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57b0: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28  CONVPATH       (
57c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
57d0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
57e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
57f0: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20  _VTAB           
5800: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5810: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5830: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5840: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5850: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5870: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5880: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5890: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
58a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
58b0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
58c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
58d0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
58e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58f0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5900: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5910: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5920: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5930: 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b  E_ABORT_ROLLBACK
5940: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5950: 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29  E_ABORT | (2<<8)
5960: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43  _CONSTRAINT_CHEC
5980: 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  K        (SQLITE
5990: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31  _CONSTRAINT | (1
59a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59c0: 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51  COMMITHOOK   (SQ
59d0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59e0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
59f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a00: 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20  INT_FOREIGNKEY  
5a10: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a20: 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  INT | (3<<8)).#d
5a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a40: 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e  STRAINT_FUNCTION
5a50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a60: 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29  STRAINT | (4<<8)
5a70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e  _CONSTRAINT_NOTN
5a90: 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45  ULL      (SQLITE
5aa0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35  _CONSTRAINT | (5
5ab0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5ad0: 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51  PRIMARYKEY   (SQ
5ae0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5af0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
5b00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5b10: 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20  INT_TRIGGER     
5b20: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5b30: 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  INT | (7<<8)).#d
5b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5b50: 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20  STRAINT_UNIQUE  
5b60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b70: 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29  STRAINT | (8<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42  _CONSTRAINT_VTAB
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39  _CONSTRAINT | (9
5bc0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5bd0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5be0: 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51  ROWID        (SQ
5bf0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5c00: 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e  |(10<<8)).#defin
5c10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c20: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
5c30: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c40: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5c50: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c60: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
5c70: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c80: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5c90: 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47  e SQLITE_WARNING
5ca0: 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20  _AUTOINDEX      
5cb0: 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47   (SQLITE_WARNING
5cc0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5cd0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55  ne SQLITE_AUTH_U
5ce0: 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20  SER             
5cf0: 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c    (SQLITE_AUTH |
5d00: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
5d10: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
5d20: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
5d30: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
5d40: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5d50: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
5d60: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
5d70: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
5d80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
5d90: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
5da0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
5db0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5dc0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
5dd0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
5de0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5df0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5e00: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5e10: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
5e20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5e40: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
5e50: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
5e60: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5e70: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5e90: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5ea0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5eb0: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5ec0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5ed0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5ee0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5ef0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5f00: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
5f10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5f20: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
5f30: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
5f40: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
5f50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5f60: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5f70: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5f80: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5f90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5fa0: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
5fb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5fc0: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
5fd0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5fe0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5ff0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
6000: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6010: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
6020: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6030: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6040: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6050: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6060: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6070: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6080: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6090: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
60a0: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
60b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
60c0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
60d0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
60e0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
60f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6100: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
6110: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
6120: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
6130: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6140: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6150: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6160: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6170: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6180: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6190: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
61a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
61b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
61c0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
61d0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
61e0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
61f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6200: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
6210: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
6220: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6230: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6240: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6250: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6260: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6270: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6280: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6290: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62a0: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
62b0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
62c0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
62d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
62e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62f0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
6300: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
6310: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6320: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6330: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6340: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6350: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6360: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6370: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6380: 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54  TE_OPEN_FILEPROT
6390: 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20  ECTION_MASK     
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63b0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
63c0: 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72  700000../* Reser
63d0: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
63e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
63f0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
6400: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
6410: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
6420: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
6430: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6440: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6450: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6460: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6470: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6480: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6490: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
64a0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
64b0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
64c0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
64d0: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
64e0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
64f0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6500: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6510: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6520: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
6530: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6540: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6550: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6560: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6570: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6580: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6590: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
65a0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
65b0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
65c0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
65d0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
65e0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
65f0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6600: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6610: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6620: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
6630: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6640: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6650: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6660: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6670: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6680: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6690: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
66a0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
66b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
66c0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
66d0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
66e0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
66f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6700: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6710: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6720: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
6730: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6740: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6750: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6760: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6770: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6780: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6790: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
67a0: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
67b0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
67c0: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
67d0: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
67e0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
67f0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6800: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6810: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6820: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
6830: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6840: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6850: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6860: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6870: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6880: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
68a0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
68b0: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
68c0: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
68d0: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
68e0: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
68f0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
6900: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6910: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6920: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6930: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6940: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6950: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6960: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6970: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6980: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6990: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69a0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
69b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
69c0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
69d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
69e0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
69f0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6a00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a10: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6a20: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a40: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6a50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a60: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6a70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a80: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6a90: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ab0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6ac0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6ad0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6ae0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6af0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6b00: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b20: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6b30: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b40: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6b50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6b60: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6b70: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6b80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b90: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6ba0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6bb0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6bc0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6bd0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6be0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6bf0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6c00: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6c10: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6c20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c30: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6c40: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6c50: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6c60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6c70: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6c80: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6c90: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6ca0: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6cb0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6cc0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6cd0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6ce0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6cf0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6d00: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6d10: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6d20: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6d30: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6d40: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6d50: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6d60: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6d70: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6d90: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6da0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6db0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6dc0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6dd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6de0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6df0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6e00: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6e10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6e20: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6e30: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6e40: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6e50: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6e60: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6e70: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6e80: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6e90: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6ea0: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6eb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6ec0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6ed0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6ee0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6ef0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6f00: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6f10: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6f20: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6f30: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6f40: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6f50: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
6f60: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
6f70: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
6f80: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6f90: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
6fa0: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
6fb0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
6fc0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
6fd0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6fe0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
6ff0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
7000: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
7010: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
7020: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
7030: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
7040: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7050: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7060: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7070: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7080: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7090: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
70a0: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
70b0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
70c0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
70d0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
70e0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
70f0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
7100: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
7110: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7120: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
7130: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7140: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7150: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7160: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7170: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7180: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7190: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
71a0: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
71b0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
71c0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
71d0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
71e0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
71f0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
7200: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
7210: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7220: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
7230: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7240: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7250: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7260: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7270: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7280: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7290: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
72a0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
72b0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
72c0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
72d0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
72e0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
72f0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
7300: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
7310: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7320: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
7330: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7340: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7350: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7360: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7370: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7380: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7390: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
73a0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
73b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
73c0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
73d0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
73e0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
73f0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
7400: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
7410: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7420: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
7430: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7440: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7450: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7460: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7470: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7480: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7490: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
74a0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
74b0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
74c0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
74d0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
74e0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
74f0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7500: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7510: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7520: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
7530: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7540: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7550: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7560: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7570: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7580: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7590: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
75a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
75b0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
75c0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
75d0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
75e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
75f0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
7600: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7610: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7620: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
7630: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7640: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7650: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7670: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7680: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7690: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
76a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
76b0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
76c0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
76d0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
76e0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
76f0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7700: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7710: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7720: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
7730: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7740: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7750: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7760: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7770: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7780: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7790: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
77a0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
77b0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
77c0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
77d0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
77e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
77f0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
7800: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7810: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7820: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7830: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7840: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7850: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7860: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7870: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7880: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7890: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
78a0: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
78b0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
78c0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
78d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
78e0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
78f0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
7900: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7910: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7920: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
7930: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7940: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7950: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7960: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7970: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7980: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7990: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
79a0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
79b0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
79c0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
79d0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
79e0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
79f0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7a00: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7a10: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7a20: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
7a30: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
7a40: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7a50: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7a60: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7a70: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7a80: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7a90: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7aa0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7ab0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7ac0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7ad0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7ae0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7af0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7b00: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7b10: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7b20: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7b30: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7b40: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7b50: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7b60: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7b70: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7b80: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7b90: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7ba0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7bb0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7bc0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7bd0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7be0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7bf0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7c00: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7c10: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7c20: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7c30: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7c40: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7c50: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7c60: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7c70: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7c80: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7c90: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7ca0: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7cb0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7cc0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7cd0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7ce0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7cf0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7d00: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7d10: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7d20: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7d30: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7d40: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7d50: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7d60: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7d70: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7d80: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7d90: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7da0: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7db0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7dc0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7dd0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7de0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7df0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7e00: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7e10: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7e20: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7e30: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7e40: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7e50: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7e60: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7e70: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7e80: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7e90: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7ea0: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7eb0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7ec0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7ed0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7ee0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7ef0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7f00: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7f10: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7f20: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7f30: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7f40: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7f50: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7f60: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7f70: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7f80: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7f90: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7fa0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7fb0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7fc0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7fd0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7fe0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7ff0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
8000: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
8010: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8020: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8030: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8040: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8050: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8060: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8070: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8080: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8090: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
80a0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
80b0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
80c0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
80d0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
80e0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
80f0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
8100: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8110: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8120: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8130: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8140: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8150: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8160: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8170: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8180: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8190: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
81a0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
81b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
81c0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
81d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81e0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
81f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8200: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8210: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8220: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8230: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8240: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8250: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8260: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8270: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8280: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8290: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
82a0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
82b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
82c0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
82d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82e0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
82f0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8300: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8310: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8320: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8330: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8340: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8350: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8360: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8370: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8380: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8390: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
83a0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
83b0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
83c0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
83d0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
83e0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
83f0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8400: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8410: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8420: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8430: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8440: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8450: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8460: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8470: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8480: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8490: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
84a0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
84b0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
84c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
84d0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
84e0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
84f0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8500: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8510: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8520: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8530: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
8540: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8560: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8570: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8580: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8590: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
85a0: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
85b0: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
85c0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
85d0: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
85e0: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
85f0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
8600: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
8610: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
8620: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
8630: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
8640: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8650: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8660: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8670: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8680: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8690: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
86a0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
86b0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
86c0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
86e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86f0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8700: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8710: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8720: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
8730: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
8740: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8750: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8760: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8770: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8780: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8790: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
87a0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
87b0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
87c0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
87d0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
87e0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
87f0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
8800: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
8810: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8820: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
8830: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8840: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8850: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8860: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8870: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8880: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8890: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
88a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
88b0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
88c0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
88d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
88e0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
88f0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8900: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8910: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8920: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8930: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8940: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8950: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8960: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8970: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8980: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8990: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
89a0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
89b0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
89c0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
89d0: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
89e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
89f0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8a00: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a10: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8a20: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8a30: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8a40: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8a50: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8a60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a70: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8a80: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8a90: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8aa0: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8ab0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8ac0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8ad0: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8ae0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8af0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8b00: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8b10: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8b20: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8b30: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8b40: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8b50: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8b60: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8b70: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8b80: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8b90: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8ba0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8bb0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8bc0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8bd0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8be0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8bf0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8c00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8c10: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8c20: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8c30: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8c40: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8c50: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8c60: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8c70: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8c80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c90: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8ca0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8cb0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8cc0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8cd0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8ce0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8cf0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8d00: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8d10: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8d20: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8d30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8d40: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8d50: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8d60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8d70: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8d80: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8d90: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8da0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8db0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8dc0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8dd0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8de0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8df0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8e00: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8e10: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8e20: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8e30: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8e40: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8e50: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8e60: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8e70: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8e80: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8e90: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8ea0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8eb0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8ec0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8ed0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8ee0: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8ef0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8f00: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8f10: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8f20: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8f30: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8f40: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8f50: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8f60: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8f70: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8f80: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8f90: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8fa0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8fb0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8fc0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8fd0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8fe0: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8ff0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9000: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
9010: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9020: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
9030: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9040: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
9050: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9060: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9070: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9080: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9090: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
90a0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
90b0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
90c0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
90d0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
90e0: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
90f0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
9100: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
9110: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
9120: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
9130: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
9140: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
9150: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9160: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9170: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9180: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9190: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
91a0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
91b0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
91c0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
91d0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
91e0: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
91f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9200: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9210: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9220: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9230: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9240: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9250: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9260: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9270: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9280: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9290: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
92a0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
92b0: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
92c0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
92d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
92e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
92f0: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
9300: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9310: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
9320: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9330: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9340: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9350: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9360: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9370: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
9380: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
9390: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
93a0: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
93b0: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
93c0: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
93d0: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
93e0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
93f0: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
9400: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
9410: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
9420: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9430: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
9440: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
9450: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9460: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
9470: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9480: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
9490: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
94a0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
94b0: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
94c0: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
94d0: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
94e0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
94f0: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
9500: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
9510: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
9520: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
9530: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
9540: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
9550: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
9560: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
9570: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
9580: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
9590: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
95a0: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
95b0: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
95c0: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
95d0: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
95e0: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
95f0: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
9600: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
9610: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
9620: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
9630: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9640: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
9650: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
9660: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
9670: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
9680: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
9690: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
96a0: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
96b0: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
96c0: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
96d0: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
96e0: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
96f0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
9700: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
9710: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9720: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
9730: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
9740: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
9750: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9760: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9770: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9780: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
9790: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
97a0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
97b0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
97c0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
97d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
97e0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
97f0: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
9800: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
9810: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
9820: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9830: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9840: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
9850: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9860: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
9870: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
9880: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
9890: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
98a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
98b0: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
98c0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
98d0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
98e0: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
98f0: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9900: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9910: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9920: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
9930: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9940: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9950: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9960: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
9970: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9980: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9990: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
99a0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
99b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
99c0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
99d0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
99e0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
99f0: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9a00: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9a10: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9a20: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9a30: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9a40: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9a50: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9a60: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
9a70: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
9a80: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
9a90: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
9aa0: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9ab0: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9ac0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9ad0: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9ae0: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9af0: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9b00: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9b10: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9b20: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9b30: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9b40: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9b50: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9b60: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
9b70: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
9b80: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
9b90: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
9ba0: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9bb0: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9bc0: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9bd0: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9be0: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9bf0: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9c00: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9c10: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9c20: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9c30: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9c40: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9c50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9c60: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9c70: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
9c80: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
9c90: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
9ca0: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9cb0: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9cc0: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
9cd0: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
9ce0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
9cf0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
9d00: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
9d10: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
9d20: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
9d30: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
9d40: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
9d50: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
9d60: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
9d70: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
9d80: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
9d90: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
9da0: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
9db0: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
9dc0: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
9dd0: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
9de0: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
9df0: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
9e00: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9e10: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9e20: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9e30: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9e40: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
9e50: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9e60: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9e70: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
9e80: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
9e90: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
9ea0: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
9eb0: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
9ec0: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
9ed0: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
9ee0: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
9ef0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
9f00: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
9f10: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
9f20: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
9f30: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
9f40: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
9f50: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
9f60: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
9f70: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
9f80: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
9f90: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
9fa0: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
9fb0: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
9fc0: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
9fd0: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
9fe0: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
9ff0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a000: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a010: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a020: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a030: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a040: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
a050: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a060: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
a070: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
a080: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
a090: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
a0a0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a0b0: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a0c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a0d0: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a0e0: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a0f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a100: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a110: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a120: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
a130: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
a140: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
a150: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
a160: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a170: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a180: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a190: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a1a0: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
a1b0: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
a1c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a1d0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a1e0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a1f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a200: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a210: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a220: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a230: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a240: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
a250: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
a260: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
a270: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
a280: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
a290: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
a2a0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
a2b0: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
a2c0: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
a2d0: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
a2e0: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
a2f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a300: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a310: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a320: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a330: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a340: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a350: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a360: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
a370: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
a380: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
a390: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
a3a0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a3b0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a3c0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a3d0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a3e0: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
a3f0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
a400: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a410: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
a420: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a430: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a440: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
a450: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
a460: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
a470: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
a480: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
a490: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
a4a0: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
a4b0: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
a4c0: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
a4d0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
a4e0: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
a4f0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
a500: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
a510: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
a520: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
a530: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
a540: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a550: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
a560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a570: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
a580: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
a590: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
a5a0: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
a5b0: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
a5c0: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
a5d0: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
a5e0: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
a5f0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
a600: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
a610: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a620: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
a630: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
a640: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
a650: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
a660: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
a670: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
a680: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
a690: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a6a0: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
a6b0: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
a6c0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
a6d0: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
a6e0: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
a6f0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
a700: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
a710: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
a720: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
a730: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
a740: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
a750: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
a760: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
a770: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a780: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
a790: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
a7a0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a7b0: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
a7c0: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
a7d0: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
a7e0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
a7f0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
a800: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a810: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
a820: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
a830: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a840: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
a850: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
a860: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
a870: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
a880: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
a890: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
a8a0: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
a8b0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
a8c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a8d0: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
a8e0: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
a8f0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
a900: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
a910: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
a920: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
a930: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
a940: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
a950: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
a960: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
a970: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
a980: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
a990: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
a9a0: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
a9b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a9c0: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
a9d0: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
a9e0: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
a9f0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
aa00: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
aa10: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aa20: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
aa30: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
aa40: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
aa50: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
aa60: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
aa70: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
aa80: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
aa90: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
aaa0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
aab0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
aac0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
aad0: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
aae0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
aaf0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
ab00: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
ab10: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
ab20: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
ab30: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ab40: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
ab50: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
ab60: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
ab70: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
ab80: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
ab90: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
aba0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
abb0: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
abc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
abd0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
abe0: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
abf0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
ac00: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
ac10: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
ac20: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
ac30: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
ac40: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
ac50: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
ac60: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
ac70: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
ac80: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
ac90: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
aca0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
acb0: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
acc0: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
acd0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
ace0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
acf0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
ad00: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
ad10: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
ad20: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
ad30: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
ad40: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
ad50: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ad60: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
ad70: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
ad80: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
ad90: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
ada0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
adb0: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
adc0: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
add0: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
ade0: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
adf0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
ae00: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
ae10: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
ae20: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
ae30: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
ae40: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
ae50: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
ae60: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
ae70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ae80: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
ae90: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
aea0: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
aeb0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
aec0: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
aed0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
aee0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
aef0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
af00: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
af10: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
af20: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
af30: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
af40: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
af50: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
af60: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
af70: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
af80: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
af90: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
afa0: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
afb0: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
afc0: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
afd0: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
afe0: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
aff0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b000: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b010: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b020: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b030: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b040: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
b050: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
b060: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
b070: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
b080: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
b090: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
b0a0: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
b0b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
b0c0: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
b0d0: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
b0e0: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
b0f0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
b100: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
b110: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
b120: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
b130: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
b140: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
b150: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
b160: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
b170: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
b180: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
b190: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
b1a0: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
b1b0: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
b1c0: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
b1d0: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
b1e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
b1f0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
b200: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
b210: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
b220: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
b230: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
b240: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
b250: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
b260: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
b270: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
b280: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
b290: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
b2a0: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
b2b0: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
b2c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b2d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b2e0: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
b2f0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
b300: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
b310: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b320: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
b330: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
b340: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
b350: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b360: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
b370: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
b380: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
b390: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
b3a0: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b3b0: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
b3c0: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
b3d0: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
b3e0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b3f0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
b400: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
b410: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
b420: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
b430: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
b440: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b450: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b460: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b470: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b480: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b490: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b4a0: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b4b0: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b4c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b4d0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b4e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b4f0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b500: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b510: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b520: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b530: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b540: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b550: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b560: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b570: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b580: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b590: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b5a0: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b5b0: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b5c0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b5d0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b5e0: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b5f0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b600: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b610: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b620: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b630: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b640: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b650: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b660: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b670: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b680: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b690: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b6a0: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b6b0: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b6c0: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b6d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b6e0: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b6f0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b700: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b710: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b720: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b730: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b740: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b750: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b760: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b770: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b780: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b790: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b7a0: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b7b0: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b7c0: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b7d0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b7e0: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b7f0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b800: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b810: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b820: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b830: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b840: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b850: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
b860: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
b870: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
b880: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
b890: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
b8a0: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
b8b0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
b8c0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
b8d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b8e0: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
b8f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b900: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
b910: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
b920: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
b930: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
b940: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
b950: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
b960: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
b970: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
b980: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
b990: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
b9a0: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
b9b0: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
b9c0: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
b9d0: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
b9e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
b9f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
ba00: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
ba10: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
ba20: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
ba30: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
ba40: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
ba50: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
ba60: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
ba70: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
ba80: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
ba90: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
baa0: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
bab0: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
bac0: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
bad0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
bae0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
baf0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
bb00: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
bb10: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
bb20: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
bb30: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bb40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
bb50: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
bb60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
bb70: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
bb80: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
bb90: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
bba0: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
bbb0: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
bbc0: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
bbd0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
bbe0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
bbf0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
bc00: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
bc10: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
bc20: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
bc30: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
bc40: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
bc50: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
bc60: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
bc70: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
bc80: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
bc90: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
bca0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
bcb0: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
bcc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
bcd0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
bce0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
bcf0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
bd00: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
bd10: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
bd20: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
bd30: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
bd40: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
bd50: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
bd60: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bd70: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
bd80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
bd90: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
bda0: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
bdb0: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
bdc0: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
bdd0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
bde0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
bdf0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
be00: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
be10: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
be20: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
be30: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
be40: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
be50: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
be60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
be70: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
be80: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
be90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
bea0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
beb0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
bec0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
bed0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
bee0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
bef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
bf00: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
bf10: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
bf20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
bf30: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
bf40: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
bf50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
bf60: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
bf70: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
bf80: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
bf90: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
bfa0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
bfb0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
bfc0: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
bfd0: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
bfe0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
bff0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
c000: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c010: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
c020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
c030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c040: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
c050: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
c060: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c070: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
c080: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
c090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c0a0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
c0b0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
c0c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c0d0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
c0e0: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
c0f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c100: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
c110: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
c120: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c130: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
c140: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
c150: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c160: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
c170: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
c180: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
c190: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
c1a0: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
c1b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c1c0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
c1d0: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
c1e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c1f0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
c200: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
c210: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c220: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
c230: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
c240: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c250: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
c260: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
c270: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c290: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
c2a0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
c2b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c2c0: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
c2d0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
c2e0: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
c2f0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c300: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
c310: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
c320: 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20  ../* deprecated 
c330: 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  names */.#define
c340: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
c350: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
c360: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
c370: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
c380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
c390: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c3a0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
c3b0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
c3c0: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
c3d0: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
c3e0: 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f           SQLITE_
c3f0: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
c400: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
c410: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
c420: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
c430: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
c440: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
c450: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
c460: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
c470: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
c480: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
c490: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
c4a0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
c4b0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
c4c0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
c4d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
c4e0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
c4f0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
c500: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
c510: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
c520: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
c530: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
c540: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
c550: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
c560: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
c570: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
c580: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
c590: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
c5a0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
c5b0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
c5c0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
c5d0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
c5e0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
c5f0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
c600: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
c610: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
c620: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
c630: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
c640: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
c650: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
c660: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
c670: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
c680: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
c690: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
c6a0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
c6b0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
c6c0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
c6d0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
c6e0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
c6f0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
c700: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
c710: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
c720: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
c730: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
c740: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
c750: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
c760: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
c770: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
c780: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
c790: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
c7a0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
c7b0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
c7c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
c7d0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
c7e0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
c7f0: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
c800: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
c810: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
c820: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
c830: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
c840: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
c850: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
c860: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
c870: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
c880: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
c890: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
c8a0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
c8b0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
c8c0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
c8d0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
c8e0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
c8f0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
c900: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
c910: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
c920: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
c930: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
c940: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
c950: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
c960: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
c970: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
c980: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
c990: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
c9a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c9b0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
c9c0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
c9d0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
c9e0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
c9f0: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
ca00: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
ca10: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
ca20: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
ca30: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
ca40: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
ca50: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
ca60: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
ca70: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
ca80: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
ca90: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
caa0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
cab0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
cac0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
cad0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
cae0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
caf0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
cb00: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
cb10: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
cb20: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
cb30: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
cb40: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
cb50: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
cb60: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
cb70: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
cb80: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
cb90: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
cba0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
cbb0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
cbc0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
cbd0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
cbe0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
cbf0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
cc00: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
cc10: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
cc20: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
cc30: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
cc40: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
cc50: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
cc60: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
cc70: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
cc80: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
cc90: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
cca0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
ccb0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
ccc0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
ccd0: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
cce0: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
ccf0: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
cd00: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
cd10: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
cd20: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
cd30: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
cd40: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
cd50: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
cd60: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
cd70: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
cd80: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
cd90: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
cda0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
cdb0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
cdc0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
cdd0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
cde0: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
cdf0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
ce00: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
ce10: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
ce20: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
ce30: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
ce40: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
ce50: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
ce60: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
ce70: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
ce80: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
ce90: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
cea0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
ceb0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
cec0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
ced0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
cee0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
cef0: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
cf00: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
cf10: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
cf20: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
cf30: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
cf40: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
cf50: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
cf60: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
cf70: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
cf80: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
cf90: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
cfa0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
cfb0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
cfc0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
cfd0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
cfe0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
cff0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
d000: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
d010: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
d020: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
d030: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
d040: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
d050: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
d060: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
d070: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
d080: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
d090: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
d0a0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
d0b0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
d0c0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
d0d0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
d0e0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d0f0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d100: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
d110: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
d120: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
d130: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
d140: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
d150: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
d160: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d170: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
d180: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d190: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
d1a0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
d1b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
d1c0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d1d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d1e0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
d1f0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d200: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
d210: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d220: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
d230: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d240: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
d250: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
d260: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
d270: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
d280: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
d290: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
d2a0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
d2b0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
d2c0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
d2d0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
d2e0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
d2f0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
d300: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
d310: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
d320: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
d330: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
d340: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
d350: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
d360: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
d370: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
d380: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
d390: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
d3a0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
d3b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
d3c0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
d3d0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
d3e0: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
d3f0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
d400: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
d410: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
d420: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
d430: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
d440: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
d450: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
d460: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
d470: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
d480: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
d490: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
d4a0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
d4b0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
d4c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
d4d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
d4e0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
d4f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d500: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
d510: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
d520: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d530: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
d540: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
d550: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
d560: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
d570: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
d580: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d590: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
d5a0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
d5b0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
d5c0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
d5d0: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
d5e0: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
d5f0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
d600: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
d610: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
d620: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
d630: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
d640: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
d650: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
d660: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
d670: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
d680: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
d690: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
d6a0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
d6b0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
d6c0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
d6d0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
d6e0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
d6f0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
d700: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
d710: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
d720: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
d730: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
d740: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
d750: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
d760: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
d770: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
d780: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
d790: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
d7a0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
d7b0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
d7c0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
d7d0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
d7e0: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
d7f0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
d800: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
d810: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
d820: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
d830: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
d840: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
d850: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
d860: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
d870: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
d880: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
d890: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
d8a0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
d8b0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
d8c0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
d8d0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d8e0: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
d8f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d900: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
d910: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
d920: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
d930: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
d940: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
d950: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
d960: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
d970: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
d980: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
d990: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
d9a0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
d9b0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
d9c0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
d9d0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
d9e0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
d9f0: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
da00: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
da10: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
da20: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
da30: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
da40: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
da50: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
da60: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
da70: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
da80: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
da90: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
daa0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
dab0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
dac0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
dad0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
dae0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
daf0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
db00: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
db10: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
db20: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
db30: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
db40: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
db50: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
db60: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
db70: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
db80: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
db90: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
dba0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
dbb0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
dbc0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
dbd0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
dbe0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
dbf0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
dc00: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
dc10: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
dc20: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
dc30: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
dc40: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
dc50: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
dc60: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
dc70: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
dc80: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
dc90: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
dca0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
dcb0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
dcc0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
dcd0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
dce0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
dcf0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
dd00: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
dd10: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
dd20: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
dd30: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
dd40: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
dd50: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
dd60: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
dd70: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
dd80: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
dd90: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
dda0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
ddb0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
ddc0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
ddd0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
dde0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
ddf0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
de00: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
de10: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
de20: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
de30: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
de40: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
de50: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
de60: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
de70: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
de80: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
de90: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
dea0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
deb0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
dec0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
ded0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
dee0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
def0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
df00: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
df10: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
df20: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
df30: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
df40: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
df50: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
df60: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
df70: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
df80: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
df90: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
dfa0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
dfb0: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
dfc0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
dfd0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
dfe0: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
dff0: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
e000: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
e010: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e020: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
e030: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
e040: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
e050: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
e060: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
e070: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
e080: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
e090: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
e0a0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
e0b0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
e0c0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
e0d0: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
e0e0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
e0f0: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
e100: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
e110: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
e120: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
e130: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
e140: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
e150: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
e160: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
e170: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
e180: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
e190: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
e1a0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
e1b0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
e1c0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
e1d0: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
e1e0: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
e1f0: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
e200: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
e210: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
e220: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
e230: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
e240: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
e250: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
e260: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
e270: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
e280: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
e290: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
e2a0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
e2b0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
e2c0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
e2d0: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
e2e0: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
e2f0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
e300: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
e310: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
e320: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
e330: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
e340: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
e350: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
e360: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
e370: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
e380: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
e390: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
e3a0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
e3b0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
e3c0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
e3d0: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
e3e0: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
e3f0: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
e400: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
e410: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
e420: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
e430: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
e440: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
e450: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
e460: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
e470: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
e480: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
e490: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
e4a0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
e4b0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
e4c0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
e4d0: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
e4e0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
e4f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
e500: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
e510: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
e520: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
e530: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
e540: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
e550: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
e560: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
e570: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
e580: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
e590: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
e5a0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
e5b0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
e5c0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
e5d0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
e5e0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
e5f0: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
e600: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
e610: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
e620: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
e630: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e640: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
e650: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
e660: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
e670: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
e680: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
e690: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
e6a0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e6b0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
e6c0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
e6d0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
e6e0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e6f0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
e700: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
e710: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
e720: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
e730: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e740: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
e750: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
e760: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
e770: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
e780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
e790: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
e7a0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
e7b0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
e7c0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
e7d0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
e7e0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
e7f0: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
e800: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
e810: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
e820: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
e830: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
e840: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
e850: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
e860: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
e870: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
e880: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
e890: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
e8a0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
e8b0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e8c0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
e8d0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
e8e0: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
e8f0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
e900: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
e910: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e920: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e930: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
e940: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e950: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
e960: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
e970: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
e980: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
e990: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
e9a0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e9b0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
e9c0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
e9d0: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
e9e0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
e9f0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
ea00: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
ea10: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
ea20: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
ea30: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
ea40: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
ea50: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
ea60: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
ea70: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
ea80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ea90: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
eaa0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
eab0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
eac0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
ead0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
eae0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
eaf0: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
eb00: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
eb10: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
eb20: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
eb30: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
eb40: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
eb50: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
eb60: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
eb70: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
eb80: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
eb90: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
eba0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75  appended in futu
ebb0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
ebc0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
ebd0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
ebe0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
ebf0: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
ec00: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
ec10: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
ec20: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
ec30: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
ec40: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
ec50: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
ec60: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
ec70: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
ec80: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ec90: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
eca0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
ecb0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
ecc0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
ecd0: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
ece0: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
ecf0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
ed00: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
ed10: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
ed20: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
ed30: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
ed40: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
ed50: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
ed60: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ed70: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
ed80: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
ed90: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
eda0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
edb0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
edc0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
edd0: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
ede0: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
edf0: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
ee00: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
ee10: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
ee20: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
ee30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ee40: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
ee50: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
ee60: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
ee70: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
ee80: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
ee90: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
eea0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
eeb0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
eec0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
eed0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
eee0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
eef0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
ef00: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
ef10: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
ef20: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
ef30: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
ef40: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
ef50: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
ef60: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
ef70: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
ef80: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
ef90: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
efa0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
efb0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
efc0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
efd0: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
efe0: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
eff0: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
f000: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
f010: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f020: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
f030: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
f040: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
f050: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
f060: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
f070: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
f080: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
f090: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
f0a0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
f0b0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
f0c0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f0d0: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
f0e0: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
f0f0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
f100: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
f110: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
f120: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
f130: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f140: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
f150: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f160: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
f170: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
f180: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
f190: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f1a0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
f1b0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
f1c0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
f1d0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
f1e0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
f1f0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f200: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
f210: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
f220: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
f230: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
f240: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
f250: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
f260: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20  ** was given on 
f270: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
f280: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
f290: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
f2a0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
f2b0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
f2c0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
f2d0: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
f2e0: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
f2f0: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
f300: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
f310: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
f320: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
f330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f340: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
f350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f360: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
f370: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
f380: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
f390: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
f3a0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
f3b0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
f3c0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
f3d0: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
f3e0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
f3f0: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
f400: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
f410: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
f420: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
f430: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
f440: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
f450: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
f460: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
f470: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
f480: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
f490: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
f4a0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
f4b0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
f4c0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
f4d0: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
f4e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
f4f0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
f500: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
f510: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f520: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f530: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
f540: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
f550: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
f560: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f570: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
f580: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
f590: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
f5a0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
f5b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f5c0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
f5d0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
f5e0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
f5f0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
f600: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
f610: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
f620: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
f630: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
f640: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
f650: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
f660: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
f670: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
f680: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
f690: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
f6a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f6b0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
f6c0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
f6d0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
f6e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f6f0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
f700: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
f710: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
f720: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
f730: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
f740: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
f750: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
f760: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
f770: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
f780: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f790: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
f7a0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
f7b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f7c0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
f7d0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
f7e0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
f7f0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
f800: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
f810: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f820: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
f830: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
f840: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
f850: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
f860: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f870: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
f880: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
f890: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
f8a0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
f8b0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f8c0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
f8d0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
f8e0: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
f8f0: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
f900: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f910: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
f920: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
f930: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
f940: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
f950: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
f960: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
f970: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
f980: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
f990: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
f9a0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
f9b0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
f9c0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
f9d0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
f9e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f9f0: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
fa00: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
fa10: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
fa20: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
fa30: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
fa40: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
fa50: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fa60: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
fa70: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
fa80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fa90: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
faa0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
fab0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
fac0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
fad0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
fae0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
faf0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
fb00: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fb10: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
fb20: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
fb30: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
fb40: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
fb50: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
fb60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
fb70: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
fb80: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
fb90: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
fba0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
fbb0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
fbc0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
fbd0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
fbe0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
fbf0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
fc00: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
fc10: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
fc20: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
fc30: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
fc40: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
fc50: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
fc60: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
fc70: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
fc80: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
fc90: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
fca0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
fcb0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
fcc0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
fcd0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
fce0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
fcf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fd00: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
fd10: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
fd20: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
fd30: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
fd40: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
fd50: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
fd60: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
fd70: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
fd80: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
fd90: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
fda0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
fdb0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
fdc0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
fdd0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
fde0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
fdf0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
fe00: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fe10: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
fe20: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
fe30: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
fe40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fe50: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
fe60: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
fe70: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
fe80: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
fe90: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
fea0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
feb0: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
fec0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
fed0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
fee0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
fef0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
ff00: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
ff10: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
ff20: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
ff30: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
ff40: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
ff50: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
ff60: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
ff70: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
ff80: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
ff90: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
ffa0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
ffb0: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
ffc0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
ffd0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
ffe0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
fff0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
10000 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
10010 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
10020 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
10030 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
10040 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
10050 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
10060 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
10070 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10080 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
10090 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
100a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
100b0 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
100c0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
100d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
100e0 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
100f0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
10100 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
10110 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
10120 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
10130 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
10140 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
10150 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
10160 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
10170 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
10180 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
10190 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
101a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
101b0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
101c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
101d0 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
101e0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
101f0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
10200 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
10210 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
10220 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
10230 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
10240 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
10250 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
10260 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
10270 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
10280 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
10290 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
102a0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
102b0 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
102c0 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
102d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
102e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
102f0 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
10300 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
10310 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
10320 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
10330 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
10340 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
10350 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
10360 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
10370 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
10380 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
10390 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
103a0 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
103b0 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
103c0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
103d0 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
103e0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
103f0 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
10400 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
10410 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
10420 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
10430 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
10440 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
10450 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
10460 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
10470 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
10480 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
10490 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
104a0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
104b0 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
104c0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
104d0 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
104e0 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
104f0 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
10500 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10510 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
10520 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
10530 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
10540 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
10550 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
10560 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
10570 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
10580 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
10590 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
105a0 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
105b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
105c0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
105d0 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
105e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
105f0 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
10600 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
10610 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
10620 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
10630 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
10640 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
10650 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
10660 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
10670 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
10680 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
10690 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
106a0 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
106b0 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
106c0 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
106d0 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
106e0 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
106f0 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
10700 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65  ** <b>The sqlite
10710 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10720 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
10730 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c  adsafe. The appl
10740 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
10750 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  ensure that no o
10760 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
10770 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
10780 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
10790 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
107a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
107b0 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a   running.</b>.**
107c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
107d0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
107e0 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ce.** may only b
107f0 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
10800 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
10810 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
10820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
10830 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
10840 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
10850 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10860 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
10870 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10880 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
10890 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
108a0 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
108b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
108c0 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
108d0 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
108e0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
108f0 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
10900 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
10910 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
10920 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
10930 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10940 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
10950 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
10960 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
10970 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
10980 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
10990 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
109a0 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
109b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
109c0 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
109d0 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
109e0 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
109f0 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
10a00 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
10a10 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
10a20 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10a30 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
10a40 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
10a50 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10a60 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
10a70 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
10a80 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
10a90 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10aa0 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
10ab0 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
10ac0 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
10ad0 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
10ae0 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
10af0 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
10b00 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
10b10 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
10b20 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
10b30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10b40 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
10b50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10b60 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
10b70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
10b80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
10b90 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te3.**.** The sq
10ba0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10bb0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
10bc0 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
10bd0 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10be0 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
10bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
10c00 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
10c10 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
10c20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10c30 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
10c40 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
10c50 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
10c60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10c70 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
10c80 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
10c90 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
10ca0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
10cb0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
10cc0 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
10cd0 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
10ce0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
10cf0 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
10d00 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
10d10 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
10d20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
10d30 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
10d40 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
10d50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
10d60 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
10d70 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
10d80 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
10d90 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
10da0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10db0 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
10dc0 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
10dd0 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
10de0 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
10df0 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
10e00 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
10e10 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
10e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
10e30 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
10e40 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
10e50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
10e60 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
10e70 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
10e80 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
10e90 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
10ea0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
10eb0 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
10ec0 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
10ed0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10ee0 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
10ef0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
10f00 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
10f10 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
10f20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10f30 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
10f40 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
10f50 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
10f60 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
10f70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10f80 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
10f90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10fa0 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
10fb0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
10fc0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
10fd0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
10fe0 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
10ff0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
11000 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
11010 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
11020 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
11030 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
11040 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
11050 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
11060 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
11070 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
11080 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
11090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
110a0 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
110b0 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
110c0 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
110d0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
110e0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
110f0 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
11100 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
11110 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
11120 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
11130 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
11140 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
11150 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
11160 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
11170 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
11180 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
11190 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
111a0 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
111b0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
111c0 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
111d0 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
111e0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
111f0 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
11200 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
11210 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
11220 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
11230 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
11240 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
11250 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
11260 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
11270 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
11280 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
11290 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
112a0 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
112b0 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
112c0 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
112d0 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
112e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
112f0 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
11300 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
11310 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
11320 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
11330 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
11340 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
11350 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
11360 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
11370 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
11380 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
11390 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
113a0 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
113b0 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
113c0 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
113d0 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
113e0 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
113f0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
11400 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
11410 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
11420 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
11430 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
11440 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
11450 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
11460 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
11470 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
11480 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
11490 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
114a0 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
114b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
114c0 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
114d0 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
114e0 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
114f0 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
11500 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
11510 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
11520 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
11530 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
11540 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
11550 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
11560 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
11570 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
11580 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
11590 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
115a0 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
115b0 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
115c0 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
115d0 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
115e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
115f0 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
11600 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
11610 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
11620 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
11630 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
11640 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
11650 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
11660 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
11670 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
11680 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
11690 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
116a0 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
116b0 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
116c0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
116d0 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
116e0 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
116f0 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
11700 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
11710 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
11720 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
11730 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
11740 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
11750 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
11760 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
11770 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11780 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
11790 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
117a0 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
117b0 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
117c0 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
117d0 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
117e0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
117f0 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
11800 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
11810 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
11820 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
11830 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
11840 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
11850 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
11860 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
11870 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
11880 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
11890 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
118a0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
118b0 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
118c0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
118d0 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
118e0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
118f0 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
11900 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
11910 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
11920 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
11930 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
11940 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
11950 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
11960 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11970 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11980 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
11990 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
119a0 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
119b0 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
119c0 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
119d0 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
119e0 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
119f0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
11a00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11a10 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
11a20 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
11a30 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
11a40 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
11a50 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
11a60 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
11a70 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
11a80 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
11a90 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
11aa0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
11ab0 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
11ac0 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
11ad0 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
11ae0 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
11af0 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
11b00 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11b10 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
11b20 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
11b30 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11b40 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
11b50 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
11b60 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
11b70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11b80 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
11b90 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
11ba0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
11bb0 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
11bc0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
11bd0 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
11be0 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
11bf0 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
11c00 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
11c10 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
11c20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
11c30 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
11c40 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
11c50 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
11c60 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11c70 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
11c80 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
11c90 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
11ca0 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
11cb0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11cc0 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
11cd0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11ce0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
11cf0 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
11d00 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
11d10 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
11d20 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11d30 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
11d40 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
11d50 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
11d60 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
11d70 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
11d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11d90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
11da0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
11db0 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
11dc0 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
11dd0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
11de0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
11df0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
11e00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
11e10 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
11e20 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
11e30 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
11e40 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11e50 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
11e60 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
11e70 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11e80 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
11e90 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
11ea0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
11eb0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
11ec0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
11ed0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
11ee0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
11ef0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
11f00 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
11f10 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
11f20 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
11f30 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
11f40 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
11f50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
11f60 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
11f70 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
11f80 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
11f90 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
11fa0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
11fb0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
11fc0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
11fd0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
11fe0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
11ff0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12000 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
12010 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
12020 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
12030 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
12040 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
12050 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
12060 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
12070 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
12080 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
12090 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
120a0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
120b0 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
120c0 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
120d0 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
120e0 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
120f0 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
12100 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
12110 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
12120 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12130 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12140 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12150 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12160 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
12170 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
12180 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
12190 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
121a0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
121b0 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
121c0 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
121d0 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
121e0 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
121f0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
12200 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
12210 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12220 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
12230 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12240 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
12250 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12260 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12270 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
12280 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
12290 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
122a0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
122b0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
122c0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
122d0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
122e0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
122f0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12300 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
12310 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
12320 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
12330 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
12340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12350 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
12360 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
12370 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
12380 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
12390 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
123a0 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
123b0 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
123c0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
123d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
123e0 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
123f0 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
12400 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
12410 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
12420 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
12430 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
12440 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
12450 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
12460 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
12470 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
12480 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12490 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
124a0 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
124b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
124c0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
124d0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
124e0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
124f0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12500 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12510 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
12520 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
12530 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
12540 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12550 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
12560 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12570 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12580 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
12590 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
125a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
125b0 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
125c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
125d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
125e0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
125f0 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
12600 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12610 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12620 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12630 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12640 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12650 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12660 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12670 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
12680 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
12690 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
126a0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
126b0 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
126c0 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
126d0 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
126e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
126f0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12700 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
12710 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
12720 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
12730 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
12740 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12750 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
12760 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
12770 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
12780 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
12790 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
127a0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
127b0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
127c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
127d0 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
127e0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
127f0 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
12800 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
12810 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
12820 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
12830 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12840 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
12850 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
12860 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
12870 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12880 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
12890 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
128a0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
128b0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
128c0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
128d0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
128e0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
128f0 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
12900 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
12910 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
12920 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
12930 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12940 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12950 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12960 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12970 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
12980 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
12990 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
129a0 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
129b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
129c0 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
129d0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
129e0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74  ONFIG_MALLOC opt
129f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12a00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12a10 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
12a20 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12a30 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12a40 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12a50 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
12a60 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
12a70 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
12a80 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
12a90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12aa0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12ab0 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
12ac0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
12ad0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12ae0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
12af0 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
12b00 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
12b10 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
12b20 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
12b30 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12b40 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12b50 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
12b60 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12b70 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
12b80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12b90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12ba0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
12bb0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12bc0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12bd0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12be0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f  NFIG_GETMALLOC o
12bf0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12c00 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12c10 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
12c20 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12c30 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12c40 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12c50 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
12c60 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12c70 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
12c80 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
12c90 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
12ca0 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
12cb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12cc0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
12cd0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
12ce0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
12cf0 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
12d00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
12d10 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
12d20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
12d30 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
12d40 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
12d50 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
12d60 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
12d70 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
12d80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12d90 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12da0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12db0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
12dc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
12dd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12de0 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20  EMSTATUS option 
12df0 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
12e00 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
12e10 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65  t,.** interprete
12e20 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
12e30 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
12e40 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
12e50 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d  llection of.** m
12e60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12e70 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
12e80 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
12e90 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12ea0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
12eb0 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
12ec0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
12ed0 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
12ee0 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
12ef0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
12f00 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
12f10 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
12f20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12f30 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
12f40 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12f50 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
12f60 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
12f70 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34  sqlite3_status64
12f80 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
12f90 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
12fa0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12fb0 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
12fc0 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
12fd0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
12fe0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
12ff0 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
13000 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
13010 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
13020 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
13030 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
13040 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
13050 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
13060 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13070 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
13080 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13090 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
130a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
130b0 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e  G_SCRATCH option
130c0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
130d0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
130e0 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
130f0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72   can use for scr
13100 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28  atch memory.  ^(
13110 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
13120 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
13130 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13140 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65  RATCH:  A pointe
13150 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
13160 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
13170 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
13180 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
13190 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
131a0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
131b0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
131c0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
131d0 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
131e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
131f0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13200 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54  ions (N).)^.** T
13210 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13220 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
13230 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
13240 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
13250 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
13260 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
13270 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
13280 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72  will not use mor
13290 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
132a0 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
132b0 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  hread..** ^SQLit
132c0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
132d0 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62  uest a scratch b
132e0 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
132f0 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
13300 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
13310 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  page size..** ^I
13320 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
13330 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
13340 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
13350 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
13360 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
13370 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13380 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
13390 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
133a0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
133b0 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
133c0 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e  emory needed.<p>
133d0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70  .** ^When the ap
133e0 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64  plication provid
133f0 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66  es any amount of
13400 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
13410 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
13420 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20  CONFIG_SCRATCH, 
13430 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e  SQLite avoids un
13440 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a  necessary large.
13450 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
13460 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69  oc|heap allocati
13470 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61  ons]..** This ca
13480 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70  n help [Robson p
13490 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d  roof|prevent mem
134a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
134b0 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20  ailures] due to 
134c0 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74  heap.** fragment
134d0 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d  ation in low-mem
134e0 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73  ory embedded sys
134f0 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tems..** </dd>.*
13500 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13510 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
13520 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13530 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
13540 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
13550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13560 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70  ECACHE option sp
13570 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79  ecifies a memory
13580 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51   pool.** that SQ
13590 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
135a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
135b0 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
135c0 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a  e default page.*
135d0 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
135e0 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
135f0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13600 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f  option is a no-o
13610 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  p if an applicat
13620 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
13630 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
13640 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
13650 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  d using the [SQL
13660 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13670 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  E2]..** ^There a
13680 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
13690 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
136a0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41  FIG_PAGECACHE: A
136b0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38   pointer to.** 8
136c0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65  -byte aligned me
136d0 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65  mory (pMem), the
136e0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
136f0 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73  ge cache line (s
13700 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e  z),.** and the n
13710 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c  umber of cache l
13720 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ines (N)..** The
13730 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
13740 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
13750 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
13760 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
13770 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
13780 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
13790 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
137a0 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
137b0 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
137c0 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
137d0 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
137e0 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
137f0 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
13800 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
13810 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43   using [SQLITE_C
13820 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
13830 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68  SZ]..** ^It is h
13840 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
13850 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
13860 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68  emory,.** for th
13870 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74  e sz parameter t
13880 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  o be larger than
13890 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65   necessary.  The
138a0 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e   pMem.** argumen
138b0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
138c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
138d0 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
138e0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
138f0 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  gned block of me
13900 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
13910 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68   sz*N bytes, oth
13920 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71  erwise.** subseq
13930 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
13940 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
13950 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74  When pMem is not
13960 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
13970 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65  ll strive to use
13980 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
13990 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73  ided.** to satis
139a0 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65  fy page cache ne
139b0 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63  eds, falling bac
139c0 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  k to [sqlite3_ma
139d0 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20  lloc()] if.** a 
139e0 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
139f0 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73  is larger than s
13a00 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c  z bytes or if al
13a10 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75  l of the pMem bu
13a20 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75  ffer.** is exhau
13a30 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65  sted..** ^If pMe
13a40 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  m is NULL and N 
13a50 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
13a60 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  n each database 
13a70 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f  connection.** do
13a80 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75  es an initial bu
13a90 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  lk allocation fo
13aa0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
13ab0 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ory.** from [sql
13ac0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
13ad0 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20  ufficient for N 
13ae0 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e  cache lines if N
13af0 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a   is positive or.
13b00 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79  ** of -1024*N by
13b10 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61  tes if N is nega
13b20 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69  tive, . ^If addi
13b30 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
13b40 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
13b50 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
13b60 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
13b70 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20   the initial.** 
13b80 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
13b90 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13ba0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13bb0 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f  )] separately fo
13bc0 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69  r each.** additi
13bd0 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e  onal cache line.
13be0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13c00 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
13c10 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
13c20 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13c30 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
13c40 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13c50 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13c60 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
13c70 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
13c80 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
13c90 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
13ca0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
13cb0 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
13cc0 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
13cd0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13ce0 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
13cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13d00 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
13d10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13d20 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
13d30 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
13d40 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13d50 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
13d60 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
13d70 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
13d80 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
13d90 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
13da0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
13db0 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
13dc0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
13dd0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13de0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13df0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
13e00 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
13e10 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
13e20 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
13e30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
13e40 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
13e50 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
13e60 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
13e70 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
13e80 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
13e90 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
13ea0 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
13eb0 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
13ec0 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
13ed0 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
13ee0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
13ef0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
13f00 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
13f10 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
13f20 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
13f30 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
13f40 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
13f50 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
13f60 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
13f70 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
13f80 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
13f90 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
13fa0 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
13fb0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
13fc0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
13fd0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
13fe0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13ff0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
14000 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
14010 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
14020 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
14030 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
14040 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
14050 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
14060 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
14070 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
14080 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
14090 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
140a0 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
140b0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
140c0 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
140d0 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
140e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
140f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14100 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
14110 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
14120 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14130 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14140 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
14150 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14160 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
14170 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
14180 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14190 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
141a0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
141b0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
141c0 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
141d0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
141e0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
141f0 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
14200 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
14210 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
14220 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
14230 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
14240 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
14250 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
14260 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14270 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
14280 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
14290 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
142a0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
142b0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
142c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
142d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
142e0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
142f0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14300 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14310 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
14320 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
14330 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
14340 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
14350 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
14360 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
14370 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
14380 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
14390 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
143a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
143b0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
143c0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
143d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
143e0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
143f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14400 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
14410 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14420 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14430 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
14440 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14450 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14460 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14470 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14480 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14490 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
144a0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
144b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
144c0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
144d0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
144e0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
144f0 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
14500 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14510 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14520 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14530 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
14540 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
14550 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
14560 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
14570 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
14580 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
14590 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
145a0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
145b0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
145c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
145d0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
145e0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
145f0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14600 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14610 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14620 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14630 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14640 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14650 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
14660 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
14670 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14680 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
14690 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
146a0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
146b0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
146c0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
146d0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
146e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
146f0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
14700 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14710 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
14720 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14740 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
14750 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
14760 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
14770 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
14780 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
14790 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
147a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
147b0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
147c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
147d0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
147e0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
147f0 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
14800 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
14810 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
14820 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
14830 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
14840 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
14850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14860 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
14870 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
14880 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
14890 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
148a0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
148b0 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
148c0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
148d0 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
148e0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
148f0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
14900 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
14910 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
14920 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
14930 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14940 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
14950 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14960 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
14970 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14980 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14990 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
149a0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
149b0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
149c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
149d0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
149e0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
149f0 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
14a00 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
14a10 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
14a20 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
14a30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
14a40 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
14a50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
14a60 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14a70 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14a80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14aa0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
14ab0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14ac0 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
14ad0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14ae0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14af0 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
14b00 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14b10 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
14b20 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14b30 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14b40 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14b50 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
14b60 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
14b70 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
14b80 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
14b90 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
14ba0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14bb0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
14bc0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14bd0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
14be0 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
14bf0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14c00 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
14c10 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
14c20 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
14c30 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
14c40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14c50 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
14c60 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
14c70 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
14c80 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
14c90 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
14ca0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
14cb0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
14cc0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
14cd0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
14ce0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
14cf0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
14d00 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
14d10 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
14d20 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
14d30 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
14d40 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
14d50 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
14d60 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
14d70 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14d80 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
14d90 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
14da0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
14db0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
14dc0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
14dd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14de0 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
14df0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
14e00 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14e10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14e20 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14e30 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
14e40 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
14e50 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
14e60 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14e70 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
14e80 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
14e90 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
14ea0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14eb0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
14ec0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
14ed0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
14ee0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
14ef0 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
14f00 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
14f10 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
14f20 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
14f30 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
14f40 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
14f50 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
14f60 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
14f70 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
14f80 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
14f90 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
14fa0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
14fb0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
14fc0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14fd0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
14fe0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14ff0 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
15000 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
15010 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
15020 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
15030 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
15040 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
15050 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
15060 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
15070 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
15080 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15090 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
150a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
150b0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
150c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
150d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
150e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
150f0 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
15100 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
15110 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
15120 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
15130 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
15140 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
15150 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
15160 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
15170 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
15180 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
15190 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
151a0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
151b0 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
151c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
151d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
151e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
151f0 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
15200 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
15210 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
15220 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
15230 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
15240 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
15250 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
15260 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
15270 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
15280 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
15290 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
152a0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
152b0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
152c0 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
152d0 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
152e0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
152f0 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
15300 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
15310 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
15320 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
15330 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
15340 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
15350 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
15360 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
15370 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
15380 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
15390 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
153a0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
153b0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
153c0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
153d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
153e0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
153f0 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
15400 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15410 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
15420 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
15430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15440 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15450 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
15460 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
15470 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
15480 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
15490 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
154a0 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
154b0 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
154c0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
154d0 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
154e0 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
154f0 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
15500 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
15510 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15520 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
15530 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
15540 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
15550 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
15560 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
15570 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
15580 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
15590 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
155a0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
155b0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
155c0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
155d0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
155e0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
155f0 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
15600 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
15610 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
15620 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
15630 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
15640 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
15650 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
15660 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
15670 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
15680 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
15690 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
156a0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
156b0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
156c0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
156d0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
156e0 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
156f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
15700 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15710 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
15720 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15730 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
15740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15750 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
15760 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15770 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
15780 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
15790 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
157a0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
157b0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
157c0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
157d0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
157e0 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
157f0 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
15800 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15810 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15820 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
15830 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15840 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
15850 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
15860 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
15870 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15880 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15890 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
158a0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
158b0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
158c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
158d0 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
158e0 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
158f0 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
15900 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
15910 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
15920 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
15930 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
15940 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
15950 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
15960 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
15970 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
15980 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
15990 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
159a0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
159b0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
159c0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
159d0 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
159e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
159f0 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
15a00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15a10 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
15a20 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15a30 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
15a40 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
15a50 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
15a60 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
15a70 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
15a80 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
15a90 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
15aa0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
15ab0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
15ac0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
15ad0 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
15ae0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
15af0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
15b00 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
15b10 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
15b20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15b30 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
15b40 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
15b50 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
15b60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15b70 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
15b80 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
15b90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
15ba0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
15bb0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
15bc0 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
15bd0 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
15be0 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
15bf0 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
15c00 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
15c10 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
15c20 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
15c30 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
15c40 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15c50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15c60 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
15c70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15c80 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
15c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15ca0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
15cb0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
15cc0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
15cd0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
15ce0 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
15cf0 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
15d00 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
15d10 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
15d20 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
15d30 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
15d40 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
15d50 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
15d60 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15d70 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
15d80 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
15d90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
15da0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
15db0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
15dc0 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
15dd0 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
15de0 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
15df0 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
15e00 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
15e10 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15e20 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
15e30 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
15e40 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
15e50 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
15e60 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
15e70 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
15e80 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
15e90 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
15ea0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
15eb0 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
15ec0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
15ed0 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
15ee0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
15ef0 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
15f00 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
15f10 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
15f20 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
15f30 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
15f40 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15f50 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15f60 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
15f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15f80 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
15f90 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
15fa0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15fb0 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
15fc0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15fd0 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
15fe0 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
15ff0 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
16000 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
16010 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
16020 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
16030 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
16040 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16050 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
16060 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
16070 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
16080 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
16090 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
160a0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
160b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
160c0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
160d0 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
160e0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
160f0 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
16100 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16110 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
16120 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
16130 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
16140 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
16150 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
16160 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
16170 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
16180 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
16190 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
161a0 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
161b0 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
161c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
161d0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
161e0 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
161f0 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
16200 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
16210 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
16220 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
16230 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
16240 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
16250 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16260 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
16270 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16280 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
16290 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
162a0 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
162b0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
162c0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
162d0 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
162e0 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
162f0 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
16300 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
16310 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
16320 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
16330 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
16340 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
16350 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
16360 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
16370 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
16380 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16390 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
163a0 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
163b0 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
163c0 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
163d0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
163e0 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
163f0 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
16400 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
16410 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
16420 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
16430 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
16440 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
16450 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
16460 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
16470 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
16480 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
16490 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
164a0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
164b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
164c0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
164d0 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
164e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
164f0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
16500 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
16510 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16520 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
16530 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
16540 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16550 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
16560 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
16570 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16580 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16590 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
165a0 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
165b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
165c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
165d0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
165e0 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
165f0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16600 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16620 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
16630 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16640 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
16660 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
16670 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
16680 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
16690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
166a0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
166b0 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
166c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
166d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
166e0 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
166f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16700 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16710 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16720 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
16730 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16740 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
16750 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
16760 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
16770 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
16780 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
16790 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
167a0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
167b0 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
167c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
167d0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
167e0 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
167f0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
16800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16810 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
16820 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16830 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16840 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
16850 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
16860 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16870 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
16880 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
16890 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
168a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
168b0 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
168c0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
168d0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
168e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
168f0 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
16900 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
16910 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
16920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16930 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
16940 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
16950 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
16960 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16970 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
16980 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
16990 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
169a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
169b0 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
169c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
169d0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
169e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
169f0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
16a00 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
16a10 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
16a20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16a30 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
16a40 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
16a50 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
16a60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16a70 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
16a80 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
16a90 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
16aa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16ab0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
16ac0 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
16ad0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
16ae0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
16af0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
16b00 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
16b10 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16b20 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
16b30 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16b40 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16b50 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
16b60 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
16b70 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
16b80 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16b90 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
16ba0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
16bb0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
16bc0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
16bd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16be0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
16bf0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
16c00 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
16c10 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
16c20 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
16c30 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16c40 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
16c50 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
16c60 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
16c70 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16c80 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
16c90 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
16ca0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
16cb0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
16cc0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
16cd0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
16ce0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
16cf0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
16d00 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
16d10 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16d20 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
16d30 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16d40 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
16d50 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
16d60 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
16d70 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
16d80 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
16d90 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
16da0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
16db0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16dc0 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
16dd0 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
16de0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16df0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
16e00 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
16e10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
16e20 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
16e30 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
16e40 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
16e50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16e60 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
16e70 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16e80 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
16e90 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
16ea0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
16eb0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
16ec0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
16ed0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
16ee0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16ef0 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
16f00 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
16f10 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
16f20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
16f30 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
16f40 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
16f50 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
16f60 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
16f70 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
16f80 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
16f90 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
16fa0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
16fb0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
16fc0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
16fd0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
16fe0 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
16ff0 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
17000 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
17010 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
17020 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
17030 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
17040 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
17050 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
17060 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
17070 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
17080 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
17090 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
170a0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
170b0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
170c0 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
170d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
170e0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
170f0 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
17100 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
17110 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
17120 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
17130 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
17140 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
17150 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
17160 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
17170 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
17180 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
17190 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
171a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
171b0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
171c0 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
171d0 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
171e0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
171f0 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
17200 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
17210 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
17220 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
17230 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
17240 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
17250 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
17260 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
17270 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17280 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
17290 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
172a0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
172b0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
172c0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
172d0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
172e0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
172f0 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
17300 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
17310 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
17320 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
17330 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
17340 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
17350 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
17360 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
17370 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
17380 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
17390 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
173a0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
173b0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
173c0 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
173d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
173e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
173f0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17400 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17410 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17420 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
17430 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
17440 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
17450 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
17460 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
17470 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
17480 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
17490 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
174a0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
174b0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
174c0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
174d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
174e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
174f0 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
17500 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17510 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17520 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17530 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
17540 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
17550 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
17560 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17570 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17580 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17590 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
175a0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
175b0 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
175c0 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
175d0 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
175e0 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
175f0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17600 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
17610 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17620 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17630 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17640 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17650 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17660 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17670 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
17680 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
17690 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
176a0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
176b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
176c0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
176d0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
176e0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
176f0 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
17700 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17710 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17720 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
17730 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
17740 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74  S3_TOKENIZER</dt
17750 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17760 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17770 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17780 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75  ble the two-argu
17790 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  ment.** version 
177a0 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b  of the [fts3_tok
177b0 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69  enizer()] functi
177c0 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74  on which is part
177d0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33   of the.** [FTS3
177e0 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72  ] full-text sear
177f0 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73  ch engine extens
17800 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ion..** There sh
17810 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17820 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17830 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
17840 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
17850 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
17860 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33   to disable fts3
17870 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a  _tokenizer() or.
17880 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17890 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  nable fts3_token
178a0 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69  izer() or negati
178b0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
178c0 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61  setting.** uncha
178d0 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
178e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
178f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17900 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17910 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17920 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17930 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73  cate whether fts
17940 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64  3_tokenizer is d
17950 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
17960 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
17970 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17980 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17990 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
179a0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
179b0 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
179c0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
179d0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
179e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
179f0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
17a00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
17a10 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20 20  ASIDE           
17a20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20    1001 /* void* 
17a30 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
17a40 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
17a50 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
17a60 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a           1002 /*
17a70 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
17a80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
17a90 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
17aa0 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33 20  GER        1003 
17ab0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
17ac0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
17ad0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
17ae0 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30  S3_TOKENIZER 100
17af0 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  4 /* int int* */
17b00 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
17b10 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
17b20 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
17b30 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45  sult Codes.** ME
17b40 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
17b50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
17b60 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
17b70 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
17b80 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
17b90 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
17ba0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
17bb0 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
17bc0 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
17bd0 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
17be0 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
17bf0 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
17c00 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
17c10 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e  atibility..*/.in
17c20 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
17c30 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
17c40 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
17c50 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
17c60 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
17c70 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48  rt Rowid.** METH
17c80 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
17c90 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
17ca0 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62   most SQLite tab
17cb0 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20  les (except for 
17cc0 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
17cd0 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61  tables).** has a
17ce0 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
17cf0 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
17d00 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
17d10 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
17d20 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
17d30 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
17d40 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
17d50 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
17d60 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
17d70 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
17d80 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
17d90 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
17da0 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
17db0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
17dc0 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
17dd0 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
17de0 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
17df0 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
17e00 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
17e10 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
17e20 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
17e30 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  owid..**.** ^The
17e40 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
17e50 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e  sert_rowid(D) in
17e60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
17e70 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
17e80 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  he .** most rece
17e90 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
17ea0 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
17eb0 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
17ec0 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
17ed0 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
17ee0 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e  ection D..** ^In
17ef0 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48  serts into [WITH
17f00 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
17f10 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64  s are not record
17f20 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75  ed..** ^If no su
17f30 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17f40 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ]s into rowid ta
17f50 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  bles.** have eve
17f60 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
17f70 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17f80 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65  ction D, .** the
17f90 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  n sqlite3_last_i
17fa0 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72  nsert_rowid(D) r
17fb0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
17fc0 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
17fd0 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
17fe0 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
17ff0 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
18000 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
18010 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
18020 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
18030 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
18040 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
18050 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
18060 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
18070 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
18080 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
18090 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
180a0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
180b0 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
180c0 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
180d0 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
180e0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
180f0 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
18100 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
18110 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
18120 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
18130 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
18140 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
18150 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
18160 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
18170 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
18180 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
18190 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
181a0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
181b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
181c0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
181d0 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
181e0 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
181f0 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
18200 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
18210 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
18220 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
18230 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
18240 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
18250 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
18260 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
18270 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
18280 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
18290 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
182a0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
182b0 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
182c0 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
182d0 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
182e0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
182f0 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
18300 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
18310 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
18320 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
18330 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
18340 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
18350 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
18360 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
18370 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
18380 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
18390 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
183a0 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
183b0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
183c0 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
183d0 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
183e0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
183f0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
18400 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
18410 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
18420 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
18430 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
18440 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
18450 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
18460 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
18470 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
18480 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
18490 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
184a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
184b0 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
184c0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
184d0 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
184e0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
184f0 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
18500 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
18510 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
18520 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
18530 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
18540 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18550 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
18560 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
18570 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
18580 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
18590 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
185a0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
185b0 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
185c0 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
185d0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
185e0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
185f0 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
18600 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
18610 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
18620 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
18630 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
18640 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
18650 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
18660 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65  odified, inserte
18670 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d or.** deleted 
18680 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
18690 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
186a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
186b0 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
186c0 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61  ment on the data
186d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
186e0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
186f0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e   only parameter.
18700 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61  .** ^Executing a
18710 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
18720 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
18730 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  oes not modify t
18740 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
18750 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
18760 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ction..**.** ^On
18770 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
18780 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  directly by the 
18790 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
187a0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
187b0 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64  nt are.** consid
187c0 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79  ered - auxiliary
187d0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
187e0 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  by [CREATE TRIGG
187f0 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20  ER | triggers], 
18800 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
18810 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45   actions] or [RE
18820 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
18830 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
18840 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
18850 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20   .** Changes to 
18860 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
18870 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a  intercepted by .
18880 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  ** [INSTEAD OF t
18890 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44  rigger | INSTEAD
188a0 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72   OF triggers] ar
188b0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e  e not counted. ^
188c0 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65  The value .** re
188d0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
188e0 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65  3_changes() imme
188f0 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e  diately after an
18900 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
18910 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74  or .** DELETE st
18920 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61  atement run on a
18930 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20   view is always 
18940 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67  zero. Only chang
18950 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20  es made to real 
18960 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63  .** tables are c
18970 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  ounted..**.** Th
18980 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f  ings are more co
18990 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65  mplicated if the
189a0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
189b0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  () function is.*
189c0 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65  * executed while
189d0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
189e0 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54  am is running. T
189f0 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69  his may happen i
18a00 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  f the.** program
18a10 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67   uses the [chang
18a20 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
18a30 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f  n], or if some o
18a40 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ther callback.**
18a50 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65   function invoke
18a60 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  s sqlite3_change
18a70 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73  s() directly. Es
18a80 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a  sentially:.** .*
18a90 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
18aa0 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69   ^(Before enteri
18ab0 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  ng a trigger pro
18ac0 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72  gram the value r
18ad0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20  eturned by.**   
18ae0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61       sqlite3_cha
18af0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
18b00 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20  is saved. After 
18b10 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67  the trigger prog
18b20 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68  ram .**        h
18b30 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65  as finished, the
18b40 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20   original value 
18b50 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a  is restored.)^.*
18b60 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57  * .**   <li> ^(W
18b70 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
18b80 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53  program each INS
18b90 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20  ERT, UPDATE and 
18ba0 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20  DELETE .**      
18bb0 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73    statement sets
18bc0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18bd0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
18be0 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
18bf0 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74      upon complet
18c00 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f  ion as normal. O
18c10 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76  f course, this v
18c20 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e  alue will not in
18c30 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20  clude .**       
18c40 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72   any changes per
18c50 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72  formed by sub-tr
18c60 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73  iggers, as the s
18c70 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
18c80 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75   .**        valu
18c90 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20  e will be saved 
18ca0 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74  and restored aft
18cb0 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67  er each sub-trig
18cc0 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a  ger has run.)^.*
18cd0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e  * </ul>.** .** ^
18ce0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
18cf0 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29  if the changes()
18d00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f   SQL function (o
18d10 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73  r similar) is us
18d20 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
18d30 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  st INSERT, UPDAT
18d40 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
18d50 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
18d60 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72  rigger, it .** r
18d70 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
18d80 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   as set when the
18d90 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65   calling stateme
18da0 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69  nt began executi
18db0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ng..** ^If it is
18dc0 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63   used by the sec
18dd0 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ond or subsequen
18de0 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74  t such statement
18df0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
18e00 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74  r .** program, t
18e10 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18e20 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e  d reflects the n
18e30 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
18e40 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  dified by the .*
18e50 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52  * previous INSER
18e60 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
18e70 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
18e80 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72  thin the same tr
18e90 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  igger..**.** See
18ea0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
18eb0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
18ec0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
18ed0 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
18ee0 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
18ef0 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
18f00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
18f10 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
18f20 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
18f30 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
18f40 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
18f50 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
18f60 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
18f70 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
18f80 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
18f90 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
18fa0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
18fb0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
18fc0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18fd0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
18fe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18ff0 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
19000 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
19010 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
19020 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
19030 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
19040 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  s the total numb
19050 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72  er of rows inser
19060 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72  ted, modified or
19070 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61  .** deleted by a
19080 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  ll [INSERT], [UP
19090 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
190a0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d  ] statements com
190b0 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20  pleted.** since 
190c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
190d0 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e  nection was open
190e0 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  ed, including th
190f0 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a  ose executed as.
19100 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67  ** part of trigg
19110 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78  er programs. ^Ex
19120 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
19130 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
19140 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20  atement.** does 
19150 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76  not affect the v
19160 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
19170 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
19180 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a  hanges()..** .**
19190 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61   ^Changes made a
191a0 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69  s part of [forei
191b0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
191c0 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  are included in 
191d0 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75  the.** count, bu
191e0 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20  t those made as 
191f0 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20  part of REPLACE 
19200 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
19210 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74  ution are.** not
19220 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  . ^Changes to a 
19230 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
19240 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53  tercepted by INS
19250 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
19260 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75   .** are not cou
19270 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65  nted..** .** See
19280 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
19290 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
192a0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
192b0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
192c0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
192d0 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
192e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
192f0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
19300 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
19310 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
19320 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
19330 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
19340 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
19350 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
19360 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
19370 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
19380 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
19390 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
193a0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
193b0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
193c0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
193d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
193e0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
193f0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
19400 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19410 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
19420 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
19430 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
19440 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
19450 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
19460 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
19470 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
19480 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
19490 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
194a0 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
194b0 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
194c0 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
194d0 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
194e0 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
194f0 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
19500 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
19510 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
19520 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
19530 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
19540 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
19550 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
19560 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
19570 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
19580 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
19590 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
195a0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
195b0 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
195c0 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
195d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
195e0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
195f0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
19600 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
19610 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
19620 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
19630 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
19640 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
19650 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
19660 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
19670 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
19680 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
19690 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
196a0 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
196b0 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
196c0 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
196d0 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
196e0 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
196f0 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
19700 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
19710 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
19720 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
19730 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
19740 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
19750 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
19760 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
19770 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
19780 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
19790 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
197a0 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
197b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
197c0 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
197d0 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
197e0 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
197f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
19800 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
19810 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
19820 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
19830 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
19840 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
19850 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
19860 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
19870 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
19880 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
19890 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
198a0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
198b0 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
198c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
198d0 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
198e0 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
198f0 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
19900 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
19910 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
19920 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
19930 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
19940 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
19950 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
19960 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
19970 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
19980 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
19990 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
199a0 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
199b0 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
199c0 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
199d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
199e0 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
199f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
19a00 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
19a10 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
19a20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
19a30 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
19a40 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
19a50 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
19a60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
19a70 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
19a80 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
19a90 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19aa0 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
19ab0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
19ac0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19ad0 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
19ae0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19af0 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
19b00 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
19b10 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
19b20 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ppen..*/.void sq
19b30 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19b40 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
19b50 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
19b60 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
19b70 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
19b80 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
19b90 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
19ba0 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
19bb0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
19bc0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
19bd0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
19be0 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
19bf0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
19c00 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
19c10 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
19c20 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
19c30 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
19c40 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
19c50 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
19c60 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
19c70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
19c80 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
19c90 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
19ca0 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
19cb0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
19cc0 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
19cd0 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
19ce0 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
19cf0 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
19d00 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
19d10 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
19d20 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
19d30 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
19d40 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
19d50 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
19d60 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
19d70 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
19d80 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
19d90 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
19da0 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
19db0 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
19dc0 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
19dd0 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
19de0 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
19df0 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
19e00 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
19e10 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
19e20 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
19e30 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
19e40 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
19e50 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
19e60 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
19e70 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
19e80 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
19e90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
19ea0 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
19eb0 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
19ec0 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
19ed0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19ee0 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
19ef0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
19f00 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
19f10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
19f20 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
19f30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
19f40 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
19f50 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
19f60 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
19f70 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
19f80 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
19f90 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
19fa0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
19fb0 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
19fc0 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
19fd0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
19fe0 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
19ff0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1a000 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1a010 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1a020 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1a030 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
1a040 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
1a050 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
1a060 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1a070 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
1a080 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
1a090 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
1a0a0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1a0b0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
1a0c0 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
1a0d0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
1a0e0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1a0f0 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
1a100 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1a110 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
1a120 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
1a130 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1a140 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1a150 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1a160 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1a170 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1a180 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1a190 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
1a1a0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1a1b0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
1a1c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1a1d0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
1a1e0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
1a1f0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
1a200 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
1a210 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
1a220 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57  Y Errors.** KEYW
1a230 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64  ORDS: {busy-hand
1a240 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62  ler callback} {b
1a250 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20  usy handler}.** 
1a260 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1a280 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1a290 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73  D,X,P) routine s
1a2a0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
1a2b0 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61  unction X.** tha
1a2c0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
1a2d0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
1a2e0 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61   P whenever.** a
1a2f0 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1a300 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61  e to access a da
1a310 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73  tabase table ass
1a320 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
1a330 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1a340 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f  tion] D when ano
1a350 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
1a360 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68  r process has th
1a370 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a  e table locked..
1a380 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1a390 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e  usy_handler() in
1a3a0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
1a3b0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20  to implement.** 
1a3c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1a3d0 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52  meout()] and [PR
1a3e0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1a3f0 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  t]..**.** ^If th
1a400 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1a410 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
1a420 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69  QLITE_BUSY].** i
1a430 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1a440 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
1a450 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
1a460 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
1a470 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1a480 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
1a490 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
1a4a0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1a4b0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
1a4c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1a4d0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1a4e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1a4f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1a500 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
1a510 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
1a520 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
1a530 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1a540 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
1a550 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1a560 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1a570 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
1a580 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1a590 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
1a5a0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
1a5b0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70  * been invoked p
1a5c0 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68  reviously for th
1a5d0 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
1a5e0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1a5f0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1a600 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1a610 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1a620 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1a630 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1a640 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1a650 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
1a660 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
1a670 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
1a680 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1a690 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1a6a0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1a6b0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1a6c0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
1a6d0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1a6e0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
1a6f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
1a700 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
1a710 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
1a720 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
1a730 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
1a740 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
1a750 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
1a760 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
1a770 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
1a780 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
1a790 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
1a7a0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
1a7b0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
1a7c0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
1a7d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
1a7e0 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
1a7f0 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
1a800 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1a810 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
1a820 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
1a830 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
1a840 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
1a850 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
1a860 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
1a870 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
1a880 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
1a890 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
1a8a0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
1a8b0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
1a8c0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
1a8d0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
1a8e0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
1a8f0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
1a900 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
1a910 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
1a920 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
1a930 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1a940 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
1a950 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
1a960 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
1a970 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1a980 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
1a990 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
1a9a0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
1a9b0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
1a9c0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
1a9d0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
1a9e0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
1a9f0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
1aa00 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
1aa10 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
1aa20 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
1aa30 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
1aa40 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
1aa50 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
1aa60 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
1aa70 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
1aa80 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1aa90 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
1aaa0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1aab0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
1aac0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
1aad0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1aae0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1aaf0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
1ab00 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
1ab10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ab20 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
1ab30 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
1ab40 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
1ab50 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
1ab60 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
1ab70 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
1ab80 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1ab90 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
1aba0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
1abb0 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
1abc0 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
1abd0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
1abe0 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
1abf0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1ac00 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1ac10 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
1ac20 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
1ac30 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
1ac40 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
1ac50 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
1ac60 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1ac70 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1ac80 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
1ac90 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
1aca0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1acb0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
1acc0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
1acd0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
1ace0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
1acf0 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
1ad00 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1ad10 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
1ad20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1ad30 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
1ad40 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1ad50 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1ad60 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
1ad70 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1ad80 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
1ad90 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
1ada0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1adb0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1adc0 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
1add0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1ade0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  3.**.** ^This ro
1adf0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
1ae00 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1ae10 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
1ae20 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
1ae30 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
1ae40 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
1ae50 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
1ae60 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
1ae70 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
1ae80 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
1ae90 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
1aea0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1aeb0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1aec0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
1aed0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
1aee0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1aef0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1af00 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
1af10 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
1af20 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
1af30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
1af40 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
1af50 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  E_BUSY]..**.** ^
1af60 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1af70 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1af80 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1af90 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1afa0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1afb0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1afc0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1afd0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1afe0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1aff0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1b000 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1b010 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e  onnection] at an
1b020 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1b030 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1b040 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1b050 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1b060 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1b070 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1b080 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1b090 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1b0a0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1b0b0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1b0c0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1b0d0 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  :  [PRAGMA busy_
1b0e0 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20  timeout].*/.int 
1b0f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1b100 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1b110 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1b120 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1b130 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1b140 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1b150 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1b160 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ite3.**.** This 
1b170 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
1b180 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
1b190 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
1b1a0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1b1b0 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
1b1c0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1b1d0 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
1b1e0 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
1b1f0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
1b200 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
1b210 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
1b220 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
1b230 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
1b240 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
1b250 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
1b260 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
1b270 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
1b280 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
1b290 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
1b2a0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
1b2b0 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
1b2c0 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
1b2d0 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
1b2e0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
1b2f0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
1b300 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
1b310 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
1b320 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
1b330 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
1b340 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
1b350 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
1b360 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
1b370 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
1b380 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
1b390 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1b3a0 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
1b3b0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
1b3c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1b3d0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1b3e0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1b3f0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1b400 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1b410 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1b420 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1b430 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1b440 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1b450 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1b460 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1b470 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1b480 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1b490 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1b4a0 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1b4b0 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1b4c0 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1b4d0 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1b4e0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1b4f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1b500 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1b510 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1b520 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1b530 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1b540 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1b550 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1b560 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1b570 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1b580 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1b590 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1b5a0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1b5b0 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1b5c0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1b5d0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1b5e0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1b5f0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1b600 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1b610 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1b620 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1b630 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1b640 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1b650 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1b660 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1b670 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b680 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1b690 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1b6a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1b6b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b6c0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1b6d0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1b6e0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1b6f0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1b700 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1b710 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1b720 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b730 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1b740 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1b750 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1b760 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1b770 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1b780 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1b790 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1b7a0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1b7b0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1b7c0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1b7d0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1b7e0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1b7f0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1b800 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b810 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b820 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1b830 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b840 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1b850 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b860 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1b870 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1b880 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1b890 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1b8a0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b8b0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1b8c0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b8d0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1b8e0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b8f0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1b900 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1b910 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1b920 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1b930 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1b940 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1b950 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1b960 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1b970 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1b980 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1b990 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1b9a0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1b9b0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1b9c0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1b9d0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1b9e0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1b9f0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1ba00 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1ba10 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1ba20 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1ba30 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1ba40 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1ba50 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1ba60 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1ba70 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1ba80 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1ba90 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1baa0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1bab0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1bac0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1bad0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1bae0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1baf0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1bb00 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1bb10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1bb20 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1bb30 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1bb40 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1bb50 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1bb60 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1bb70 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1bb80 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1bb90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1bba0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1bbb0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1bbc0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1bbd0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1bbe0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1bbf0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1bc00 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1bc10 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1bc20 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1bc30 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1bc40 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1bc50 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1bc60 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1bc70 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1bc80 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1bc90 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1bca0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1bcb0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1bcc0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1bcd0 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1bce0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1bcf0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1bd00 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1bd10 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1bd20 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1bd30 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1bd40 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1bd50 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1bd60 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1bd70 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1bd80 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1bd90 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
1bda0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
1bdb0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1bdc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1bdd0 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1bde0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1bdf0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1be00 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1be10 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1be20 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1be30 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1be40 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1be50 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1be60 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1be70 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1be80 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1be90 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1bea0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1beb0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1bec0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1bed0 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1bee0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1bef0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1bf00 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
1bf10 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1bf20 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1bf30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1bf40 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1bf50 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1bf60 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1bf70 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1bf80 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1bf90 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1bfa0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1bfb0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1bfc0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1bfd0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1bfe0 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20  understand most 
1bff0 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26  of the common K&
1c000 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  R formatting opt
1c010 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f  ions,.** plus so
1c020 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f  me additional no
1c030 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61  n-standard forma
1c040 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c  ts, detailed bel
1c050 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ow..** Note that
1c060 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72   some of the mor
1c070 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74  e obscure format
1c080 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f  ting options fro
1c090 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69  m recent.** C-li
1c0a0 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20  brary standards 
1c0b0 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d  are omitted from
1c0c0 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61   this implementa
1c0d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
1c0e0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1c0f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1c100 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1c110 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1c120 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1c130 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1c140 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1c150 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1c160 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1c170 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1c180 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1c190 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1c1a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1c1b0 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1c1c0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1c1d0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1c1e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1c1f0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1c200 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1c210 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1c220 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1c230 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1c240 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1c250 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1c260 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1c270 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1c280 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1c290 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1c2a0 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1c2b0 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1c2c0 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1c2d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1c2e0 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1c2f0 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1c300 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1c310 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1c320 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1c330 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1c340 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1c350 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1c360 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1c370 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1c380 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1c390 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1c3a0 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1c3b0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1c3c0 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1c3d0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1c3e0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1c3f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1c400 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1c410 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1c420 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1c430 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1c440 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1c450 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1c460 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1c470 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1c480 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1c490 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1c4a0 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1c4b0 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1c4c0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1c4d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c4e0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1c4f0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1c500 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1c510 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1c520 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1c530 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1c540 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1c550 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1c560 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1c570 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1c580 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1c590 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1c5a0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1c5b0 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1c5c0 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1c5d0 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1c5e0 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1c5f0 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1c600 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1c610 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1c620 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1c630 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1c640 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1c650 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1c660 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1c670 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1c680 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1c690 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1c6a0 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1c6b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1c6c0 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1c6d0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1c6e0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1c6f0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1c700 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1c710 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1c720 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1c730 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1c740 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1c750 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1c760 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1c770 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1c780 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20   "%Q", "%w" and 
1c790 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
1c7a0 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
1c7b0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1c7c0 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
1c7d0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74  stitutes a nul-t
1c7e0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1c7f0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
1c800 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
1c810 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
1c820 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
1c830 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
1c840 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
1c850 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
1c860 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
1c870 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
1c880 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
1c890 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
1c8a0 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
1c8b0 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
1c8c0 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
1c8d0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
1c8e0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
1c8f0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
1c900 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
1c910 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
1c920 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1c930 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c940 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
1c950 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
1c960 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
1c970 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c980 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
1c990 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
1c9a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1c9b0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1c9c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1c9d0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1c9e0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1c9f0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1ca00 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
1ca10 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
1ca20 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1ca30 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1ca40 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1ca50 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1ca60 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1ca70 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
1ca80 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
1ca90 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
1caa0 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
1cab0 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
1cac0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
1cad0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
1cae0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1caf0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1cb00 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1cb10 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1cb20 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
1cb30 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
1cb40 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1cb50 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
1cb60 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
1cb70 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
1cb80 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
1cb90 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
1cba0 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
1cbb0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
1cbc0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1cbd0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1cbe0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1cbf0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1cc00 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
1cc10 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1cc20 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
1cc30 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
1cc40 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
1cc50 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
1cc60 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
1cc70 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
1cc80 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
1cc90 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
1cca0 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
1ccb0 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
1ccc0 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
1ccd0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
1cce0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
1ccf0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
1cd00 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
1cd10 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
1cd20 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
1cd30 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
1cd40 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
1cd50 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
1cd60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1cd70 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
1cd80 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
1cd90 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
1cda0 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
1cdb0 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
1cdc0 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
1cdd0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1cde0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1cdf0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1ce00 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1ce10 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1ce20 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
1ce30 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1ce40 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1ce50 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1ce60 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1ce70 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ce80 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
1ce90 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
1cea0 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
1ceb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1cec0 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
1ced0 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
1cee0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
1cef0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1cf00 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
1cf10 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
1cf20 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25  ption is like "%
1cf30 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69  q" except that i
1cf40 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20  t expects to.** 
1cf50 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74  be contained wit
1cf60 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65  hin double-quote
1cf70 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e  s instead of sin
1cf80 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20  gle quotes, and 
1cf90 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68  it.** escapes th
1cfa0 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63  e double-quote c
1cfb0 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64  haracter instead
1cfc0 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71   of the single-q
1cfd0 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65  uote.** characte
1cfe0 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66  r.)^  The "%w" f
1cff0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1d000 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
1d010 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e   safely insertin
1d020 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63  g.** table and c
1d030 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f  olumn names into
1d040 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53   a constructed S
1d050 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1d060 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1d070 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1d080 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1d090 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1d0a0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1d0b0 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1d0c0 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1d0d0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1d0e0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1d0f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1d100 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1d110 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1d120 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
1d130 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1d140 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
1d150 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1d160 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
1d170 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
1d180 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
1d190 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1d1a0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72  har*, ...);.char
1d1b0 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
1d1c0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1d1d0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1d1e0 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1d1f0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1d200 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1d210 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1d220 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1d230 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1d240 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1d250 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1d260 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1d270 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1d280 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1d290 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1d2a0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1d2b0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1d2c0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1d2d0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1d2e0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1d2f0 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1d300 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1d310 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1d320 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1d330 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d340 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1d350 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1d360 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1d370 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1d380 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1d390 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1d3a0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1d3b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d3c0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1d3d0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1d3e0 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1d3f0 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1d400 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1d410 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1d420 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1d430 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1d440 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1d450 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d460 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1d470 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1d480 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1d490 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69  alloc64(N) routi
1d4a0 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69  ne works just li
1d4b0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ke.** sqlite3_ma
1d4c0 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74  lloc(N) except t
1d4d0 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69  hat N is an unsi
1d4e0 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65  gned 64-bit inte
1d4f0 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1d500 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69  f a signed 32-bi
1d510 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
1d520 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
1d530 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
1d540 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
1d550 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
1d560 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1d570 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1d580 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
1d590 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
1d5a0 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
1d5b0 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
1d5c0 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
1d5d0 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
1d5e0 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
1d5f0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
1d600 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
1d610 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
1d620 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
1d630 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
1d640 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
1d650 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
1d660 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
1d670 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
1d680 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
1d690 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
1d6a0 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
1d6b0 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
1d6c0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1d6d0 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
1d6e0 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
1d6f0 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
1d700 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1d710 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
1d720 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
1d730 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
1d740 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1d750 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
1d760 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
1d770 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
1d780 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1d790 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1d7a0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1d7b0 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  c()..**.** ^The 
1d7c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d7d0 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61  X,N) interface a
1d7e0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1d7f0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1d800 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58  ory allocation X
1d810 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
1d820 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  N bytes..** ^If 
1d830 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20  the X parameter 
1d840 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1d850 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20  oc(X,N).** is a 
1d860 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1d870 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1d880 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1d890 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1d8a0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20  3_malloc(N)..** 
1d8b0 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65  ^If the N parame
1d8c0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1d8d0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a  ealloc(X,N) is z
1d8e0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
1d8f0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
1d900 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
1d910 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
1d920 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
1d930 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69  ree(X)..** ^sqli
1d940 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d950 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1d960 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1d970 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1d980 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1d990 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1d9a0 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
1d9b0 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c   memory is avail
1d9c0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1d9d0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1d9e0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1d9f0 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1da00 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1da10 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1da20 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1da30 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1da40 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1da50 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1da60 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61  3_realloc(X,N) a
1da70 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1da80 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1da90 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1daa0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
1dab0 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e  turns NULL and N
1dac0 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
1dad0 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20  en the.** prior 
1dae0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f  allocation is no
1daf0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1db00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1db10 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72  loc64(X,N) inter
1db20 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20  faces works the 
1db30 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
1db40 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1db50 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
1db60 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e   a 64-bit unsign
1db70 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  ed integer inste
1db80 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69  ad.** of a 32-bi
1db90 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
1dba0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73  ..**.** ^If X is
1dbb0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1dbc0 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  tion previously 
1dbd0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1dbe0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a  lite3_malloc(),.
1dbf0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1dc00 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  c64(), sqlite3_r
1dc10 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c  ealloc(), or sql
1dc20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
1dc30 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
1dc40 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1dc50 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
1dc60 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hat memory alloc
1dc70 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a  ation in bytes..
1dc80 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  ** ^The value re
1dc90 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1dca0 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74  3_msize(X) might
1dcb0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
1dcc0 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
1dcd0 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64   bytes requested
1dce0 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f   when X was allo
1dcf0 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73  cated.  ^If X is
1dd00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1dd10 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
1dd20 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73  msize(X) returns
1dd30 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69   zero.  If X poi
1dd40 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67  nts to something
1dd50 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20   that is not.** 
1dd60 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1dd70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1dd80 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69  on, or if it poi
1dd90 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c  nts to a formerl
1dda0 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72  y.** valid memor
1ddb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61  y allocation tha
1ddc0 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66  t has now been f
1ddd0 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  reed, then the b
1dde0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71  ehavior.** of sq
1ddf0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69  lite3_msize(X) i
1de00 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
1de10 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c  possibly harmful
1de20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1de30 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
1de40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1de50 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1de60 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1de70 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20  malloc64(), and 
1de80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1de90 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  4().** is always
1dea0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1deb0 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1dec0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1ded0 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1dee0 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1def0 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1df00 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1df10 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1df20 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1df30 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1df40 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1df50 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1df60 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1df70 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1df80 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1df90 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1dfa0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1dfb0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1dfc0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1dfd0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1dfe0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1dff0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1e000 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1e010 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1e020 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1e030 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1e040 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1e050 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1e060 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1e070 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1e080 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1e090 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1e0a0 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1e0b0 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1e0c0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1e0d0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1e0e0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1e0f0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1e100 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1e110 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1e120 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1e130 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1e140 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1e150 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1e160 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
1e170 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1e180 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
1e190 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
1e1a0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
1e1b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
1e1c0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
1e1d0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
1e1e0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
1e1f0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
1e200 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
1e210 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1e220 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
1e230 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
1e240 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
1e250 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1e260 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
1e270 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1e280 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
1e290 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
1e2a0 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
1e2b0 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
1e2c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
1e2d0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
1e2e0 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
1e2f0 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
1e300 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
1e310 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
1e320 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
1e330 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
1e340 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
1e350 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
1e360 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1e370 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
1e380 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1e390 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64(sqlite3_uint6
1e3a0 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  4);.void *sqlite
1e3b0 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1e3c0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c   int);.void *sql
1e3d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76  ite3_realloc64(v
1e3e0 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
1e3f0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
1e400 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
1e410 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20  .sqlite3_uint64 
1e420 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f  sqlite3_msize(vo
1e430 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1e440 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1e450 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
1e460 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
1e470 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
1e480 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
1e490 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
1e4a0 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
1e4b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
1e4c0 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
1e4d0 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
1e4e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1e4f0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
1e500 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
1e510 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1e520 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
1e530 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
1e540 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1e550 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
1e560 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1e570 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
1e580 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
1e590 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
1e5a0 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
1e5b0 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
1e5c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1e5d0 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
1e5e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1e5f0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
1e600 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
1e610 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
1e620 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
1e630 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
1e640 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
1e650 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1e660 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1e670 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
1e680 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1e690 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1e6a0 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
1e6b0 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
1e6c0 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
1e6d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1e6e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1e6f0 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
1e700 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
1e710 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
1e720 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
1e730 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
1e740 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
1e750 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
1e760 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1e770 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
1e780 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
1e790 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1e7a0 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
1e7b0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
1e7c0 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
1e7d0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
1e7e0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1e7f0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1e800 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
1e810 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1e820 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1e830 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
1e840 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
1e850 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
1e860 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
1e870 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
1e880 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1e890 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
1e8a0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1e8b0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1e8c0 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
1e8d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e8e0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
1e8f0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
1e900 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
1e910 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
1e920 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
1e930 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
1e940 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
1e950 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
1e960 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
1e970 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
1e980 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
1e990 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
1e9a0 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
1e9b0 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
1e9c0 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
1e9d0 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
1e9e0 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
1e9f0 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
1ea00 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
1ea10 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
1ea20 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
1ea30 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
1ea40 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
1ea50 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
1ea60 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
1ea70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
1ea80 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
1ea90 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
1eaa0 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
1eab0 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
1eac0 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72  P..** ^The P par
1ead0 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20  ameter can be a 
1eae0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1eaf0 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75  .** ^If this rou
1eb00 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65  tine has not bee
1eb10 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c  n previously cal
1eb20 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72  led or if the pr
1eb30 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68  evious.** call h
1eb40 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f  ad N less than o
1eb50 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ne or a NULL poi
1eb60 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e  nter for P, then
1eb70 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20   the PRNG is.** 
1eb80 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1eb90 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
1eba0 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
1ebb0 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a  mness method of.
1ebc0 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  ** the default [
1ebd0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1ebe0 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ect..** ^If the 
1ebf0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
1ec00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1ec10 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d  d an N of 1 or m
1ec20 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e  ore and a.** non
1ec30 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65  -NULL P then the
1ec40 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
1ec50 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
1ec60 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
1ec70 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
1ec80 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
1ec90 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
1eca0 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
1ecb0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
1ecc0 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
1ecd0 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
1ece0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1ecf0 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
1ed00 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
1ed10 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1ed20 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1ed30 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
1ed40 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
1ed50 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
1ed60 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1ed70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ed80 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
1ed90 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1eda0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
1edb0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1edc0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
1edd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
1ede0 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
1edf0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1ee00 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1ee10 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
1ee20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ee30 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
1ee40 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
1ee50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ee60 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
1ee70 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
1ee80 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
1ee90 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
1eea0 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
1eeb0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
1eec0 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
1eed0 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
1eee0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1eef0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
1ef00 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
1ef10 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
1ef20 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
1ef30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
1ef40 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
1ef50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
1ef60 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
1ef70 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1ef80 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
1ef90 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
1efa0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
1efb0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1efc0 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
1efd0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
1efe0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
1eff0 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
1f000 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
1f010 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
1f020 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
1f030 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
1f040 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f050 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
1f060 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1f070 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
1f080 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
1f090 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
1f0a0 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
1f0b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f0c0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1f0d0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1f0e0 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
1f0f0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1f100 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1f110 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
1f120 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1f130 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
1f140 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
1f150 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
1f160 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
1f170 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
1f180 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1f190 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
1f1a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1f1b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1f1c0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1f1d0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
1f1e0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
1f1f0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1f200 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
1f210 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
1f220 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
1f230 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
1f240 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1f250 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1f260 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
1f270 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
1f280 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1f290 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1f2a0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
1f2b0 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
1f2c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
1f2d0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1f2e0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1f2f0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
1f300 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
1f310 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
1f320 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
1f330 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1f340 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
1f350 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
1f360 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
1f370 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1f380 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1f390 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
1f3a0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
1f3b0 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
1f3c0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
1f3d0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
1f3e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
1f3f0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1f400 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
1f410 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1f420 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
1f430 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
1f440 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1f450 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
1f460 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
1f470 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
1f480 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
1f490 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
1f4a0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1f4b0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
1f4c0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
1f4d0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
1f4e0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
1f4f0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
1f500 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
1f510 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
1f520 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
1f530 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
1f540 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
1f550 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
1f560 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1f570 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
1f580 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
1f590 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1f5a0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1f5b0 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
1f5c0 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
1f5d0 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
1f5e0 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
1f5f0 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
1f600 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
1f610 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
1f620 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
1f630 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
1f640 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
1f650 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1f660 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
1f670 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
1f680 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
1f690 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
1f6a0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
1f6b0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
1f6c0 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
1f6d0 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
1f6e0 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
1f6f0 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
1f700 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
1f710 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
1f720 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
1f730 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
1f740 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
1f750 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
1f760 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
1f770 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
1f780 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
1f790 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
1f7a0 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
1f7b0 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
1f7c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1f7d0 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
1f7e0 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
1f7f0 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
1f800 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
1f810 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
1f820 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
1f830 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
1f840 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
1f850 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
1f860 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
1f870 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1f880 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
1f890 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
1f8a0 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
1f8b0 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
1f8c0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
1f8d0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1f8e0 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
1f8f0 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
1f900 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
1f910 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
1f920 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
1f930 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
1f940 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1f950 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
1f960 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
1f970 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
1f980 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1f990 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
1f9a0 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
1f9b0 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
1f9c0 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
1f9d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
1f9e0 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
1f9f0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1fa00 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
1fa10 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
1fa20 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
1fa30 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
1fa40 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
1fa50 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
1fa60 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
1fa70 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
1fa80 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
1fa90 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
1faa0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
1fab0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
1fac0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1fad0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1fae0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1faf0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1fb00 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1fb10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1fb20 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
1fb30 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1fb40 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1fb50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fb60 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1fb70 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1fb80 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1fb90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1fba0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1fbb0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1fbc0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1fbd0 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
1fbe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fbf0 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
1fc00 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
1fc10 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
1fc20 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
1fc30 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
1fc40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1fc50 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
1fc60 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
1fc70 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
1fc80 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
1fc90 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
1fca0 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
1fcb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1fcc0 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
1fcd0 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
1fce0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1fcf0 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
1fd00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1fd10 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1fd20 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
1fd30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fd40 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1fd50 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
1fd60 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
1fd70 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
1fd80 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
1fd90 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
1fda0 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
1fdb0 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
1fdc0 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
1fdd0 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
1fde0 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
1fdf0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
1fe00 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
1fe10 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
1fe20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
1fe30 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
1fe40 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1fe50 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
1fe60 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
1fe70 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1fe80 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1fe90 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1fea0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
1feb0 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
1fec0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fed0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
1fee0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
1fef0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1ff00 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1ff10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ff20 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1ff30 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1ff40 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1ff50 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1ff60 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1ff70 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1ff80 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1ff90 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1ffa0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1ffb0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1ffc0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1ffd0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1ffe0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1fff0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
20000 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
20010 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
20020 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
20030 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
20040 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
20050 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
20060 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
20070 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
20080 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
20090 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
200a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
200b0 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
200c0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
200d0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
200e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
200f0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
20100 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
20110 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
20120 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
20130 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
20140 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
20150 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
20160 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
20170 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
20180 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
20190 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
201a0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
201b0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
201c0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
201d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
201e0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
201f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
20200 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
20210 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
20220 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
20230 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
20240 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
20250 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
20260 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
20270 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
20280 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
20290 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
202a0 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
202b0 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
202c0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
202d0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
202e0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
202f0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
20300 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
20310 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
20320 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
20330 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
20340 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
20350 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
20360 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
20370 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
20380 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
20390 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
203a0 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
203b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
203c0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
203d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
203e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
203f0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
20400 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
20410 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
20420 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
20430 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
20440 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
20450 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
20460 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
20470 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
20480 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
20490 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
204a0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
204b0 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
204c0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
204d0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
204e0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
204f0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
20500 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20510 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20520 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
20530 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
20540 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
20550 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
20560 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
20570 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20580 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20590 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
205a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
205b0 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
205c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
205d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
205e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
205f0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
20600 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
20610 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
20620 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20630 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20640 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
20650 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
20660 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20670 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20680 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20690 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
206a0 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
206b0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
206c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
206d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
206e0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
206f0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
20700 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
20710 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20720 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20730 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
20740 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
20750 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
20760 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20770 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20780 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
20790 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
207a0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
207b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
207c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
207d0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
207e0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
207f0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20800 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20810 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20820 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
20830 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
20840 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
20850 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20860 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
20870 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
20880 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
20890 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
208a0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
208b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
208c0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
208d0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
208e0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
208f0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
20900 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
20910 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
20920 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
20930 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20940 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20950 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
20960 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
20970 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
20980 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
20990 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
209a0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
209b0 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
209c0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
209d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
209e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
209f0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
20a00 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
20a10 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
20a20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20a30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20a40 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
20a50 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
20a60 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
20a70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20a80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20a90 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
20aa0 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
20ab0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20ac0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20ad0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20ae0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
20af0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
20b00 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
20b10 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
20b20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20b30 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
20b40 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
20b50 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20b60 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
20b70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20b80 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
20b90 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
20ba0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
20bb0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20bc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20bd0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
20be0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
20bf0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
20c00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20c10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20c20 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
20c30 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
20c40 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
20c50 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
20c60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
20c70 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
20c80 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
20c90 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
20ca0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20cb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
20cc0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
20cd0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
20ce0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
20cf0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20d00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
20d10 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
20d20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
20d30 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
20d40 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20d50 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
20d60 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
20d70 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
20d80 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20d90 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20da0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
20db0 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
20dc0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
20dd0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
20de0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20df0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
20e00 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
20e10 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
20e20 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
20e30 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
20e40 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
20e50 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
20e60 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20e70 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
20e80 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
20e90 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
20ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
20eb0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
20ec0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
20ed0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
20ee0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
20ef0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
20f00 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
20f10 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
20f20 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
20f30 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
20f40 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
20f50 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
20f60 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
20f70 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
20f80 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
20f90 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20fa0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20fb0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
20fc0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
20fd0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
20fe0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
20ff0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
21000 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
21010 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
21020 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
21030 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
21040 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
21050 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
21060 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
21070 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
21080 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
21090 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
210a0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
210b0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
210c0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
210d0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
210e0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
210f0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
21100 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
21110 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
21120 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
21130 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
21140 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
21150 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
21160 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
21170 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
21180 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
21190 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
211a0 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
211b0 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
211c0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
211d0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
211e0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
211f0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
21200 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
21210 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
21220 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
21230 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
21240 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
21250 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
21260 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
21270 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
21280 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
21290 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
212a0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
212b0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
212c0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
212d0 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
212e0 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
212f0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
21300 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
21310 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
21320 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
21330 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
21340 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
21350 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
21360 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
21370 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
21380 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
21390 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
213a0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
213b0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
213c0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
213d0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
213e0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
213f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
21400 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
21410 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
21420 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
21430 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
21440 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
21450 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
21460 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
21470 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
21480 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
21490 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
214a0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
214b0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
214c0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
214d0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
214e0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
214f0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
21500 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
21510 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
21520 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
21530 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
21540 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
21550 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
21560 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
21570 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
21580 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
21590 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
215a0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
215b0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
215c0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
215d0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
215e0 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
215f0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
21600 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
21610 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
21620 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
21630 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
21640 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21650 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
21660 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
21670 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
21680 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
21690 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
216a0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
216b0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
216c0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
216d0 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
216e0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
216f0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
21700 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
21710 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
21720 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
21730 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
21740 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
21750 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
21760 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
21770 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
21780 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
21790 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
217a0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
217b0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
217c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
217d0 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
217e0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
217f0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
21800 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
21810 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
21820 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
21830 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
21840 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
21850 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
21860 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
21870 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
21880 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
21890 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
218a0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
218b0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
218c0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
218d0 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
218e0 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
218f0 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
21900 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
21910 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
21920 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
21930 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
21940 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
21950 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
21960 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
21970 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
21980 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
21990 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
219a0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
219b0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
219c0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
219d0 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
219e0 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
219f0 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
21a00 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
21a10 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
21a20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
21a30 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
21a40 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
21a50 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
21a60 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
21a70 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
21a80 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
21a90 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
21aa0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
21ab0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
21ac0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
21ad0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
21ae0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
21af0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
21b00 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
21b10 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
21b20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21b30 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
21b40 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
21b50 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
21b60 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
21b70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
21b80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
21b90 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
21ba0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
21bb0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
21bc0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
21bd0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
21be0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
21bf0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
21c00 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
21c10 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
21c20 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
21c30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21c40 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
21c50 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
21c60 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  tion.** CONSTRUC
21c70 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
21c80 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
21c90 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
21ca0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
21cb0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
21cc0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
21cd0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
21ce0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
21cf0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
21d00 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
21d10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21d20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
21d30 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
21d40 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
21d50 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
21d60 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
21d70 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
21d80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
21d90 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
21da0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
21db0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
21dc0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
21dd0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
21de0 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
21df0 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
21e00 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
21e10 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
21e20 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
21e30 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
21e40 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
21e50 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
21e60 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
21e70 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
21e80 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
21e90 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
21ea0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
21eb0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
21ec0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
21ed0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
21ee0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
21ef0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
21f00 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
21f10 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
21f20 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
21f30 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
21f40 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
21f50 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
21f60 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
21f70 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
21f80 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
21f90 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
21fa0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
21fb0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
21fc0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
21fd0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
21fe0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77  fault encoding w
21ff0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72  ill be UTF-8 for
22000 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74   databases creat
22010 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69  ed using.** sqli
22020 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
22030 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
22040 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65    ^The default e
22050 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61  ncoding for data
22060 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  bases.** created
22070 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f   using sqlite3_o
22080 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20  pen16() will be 
22090 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
220a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
220b0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
220c0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
220d0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
220e0 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
220f0 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
22100 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
22110 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
22120 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
22130 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
22140 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
22150 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
22160 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
22170 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
22180 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
22190 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
221a0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
221b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
221c0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
221d0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
221e0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
221f0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
22200 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
22210 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
22220 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
22230 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
22240 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
22250 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
22260 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
22270 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
22280 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
22290 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
222a0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
222b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
222c0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
222d0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
222e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
222f0 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
22300 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
22310 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
22320 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
22330 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
22340 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
22350 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
22360 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
22370 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
22380 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
22390 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
223a0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
223b0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
223c0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
223d0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
223e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
223f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
22400 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
22410 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
22420 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
22430 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
22440 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
22450 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
22460 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
22470 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
22480 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
22490 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
224a0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
224b0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
224c0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
224d0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
224e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
224f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
22500 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
22510 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
22520 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
22530 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22540 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
22550 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
22560 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
22570 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
22580 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
22590 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
225a0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
225b0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
225c0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
225d0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
225e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
225f0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
22600 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
22610 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
22620 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22630 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
22640 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
22650 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
22660 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
22670 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
22680 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
22690 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
226a0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
226b0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
226c0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
226d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
226e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
226f0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
22700 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
22710 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
22720 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
22730 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
22740 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
22750 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
22760 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
22770 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
22780 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
22790 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
227a0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
227b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
227c0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
227d0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
227e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
227f0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
22800 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
22810 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
22820 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
22830 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
22840 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
22850 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
22860 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
22870 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
22880 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
22890 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
228a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
228b0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
228c0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
228d0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
228e0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
228f0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
22900 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
22910 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
22920 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
22930 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
22940 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
22950 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
22960 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
22970 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22980 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
22990 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
229a0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
229b0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
229c0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
229d0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
229e0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
229f0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
22a00 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
22a10 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
22a20 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
22a30 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
22a40 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
22a50 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
22a60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22a70 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
22a80 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
22a90 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
22aa0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
22ab0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
22ac0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
22ad0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
22ae0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
22af0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
22b00 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
22b10 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
22b20 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
22b30 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
22b40 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
22b50 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
22b60 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
22b70 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
22b80 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
22b90 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
22ba0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
22bb0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
22bc0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
22bd0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
22be0 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
22bf0 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
22c00 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
22c10 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
22c20 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
22c30 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
22c40 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
22c50 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
22c60 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
22c70 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
22c80 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
22c90 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
22ca0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
22cb0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
22cc0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
22cd0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
22ce0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22cf0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
22d00 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
22d10 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
22d20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
22d30 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
22d40 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
22d50 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
22d60 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
22d70 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
22d80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
22d90 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
22da0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
22db0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
22dc0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
22dd0 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
22de0 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
22df0 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
22e00 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
22e10 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
22e20 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
22e30 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
22e40 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
22e50 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
22e60 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
22e70 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
22e80 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
22e90 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
22ea0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
22eb0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
22ec0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
22ed0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
22ee0 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
22ef0 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
22f00 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
22f10 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
22f20 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
22f30 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
22f40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
22f50 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
22f60 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
22f70 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
22f80 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
22f90 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
22fa0 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
22fb0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
22fc0 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
22fd0 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
22fe0 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
22ff0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
23000 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
23010 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
23020 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
23030 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
23040 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
23050 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
23060 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
23070 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
23080 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
23090 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
230a0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
230b0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
230c0 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
230d0 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
230e0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
230f0 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
23100 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
23110 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
23120 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
23130 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
23140 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
23150 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
23160 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
23170 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
23180 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
23190 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
231a0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
231b0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
231c0 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
231d0 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
231e0 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
231f0 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
23200 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
23210 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
23220 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
23230 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
23240 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
23250 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
23260 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
23270 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
23280 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
23290 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
232a0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
232b0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
232c0 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
232d0 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
232e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
232f0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
23300 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
23310 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
23320 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
23330 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
23340 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
23350 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
23360 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
23370 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
23380 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
23390 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
233a0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
233b0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
233c0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
233d0 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
233e0 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
233f0 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
23400 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
23410 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
23420 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
23430 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
23440 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
23450 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
23460 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
23470 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
23480 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
23490 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
234a0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
234b0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
234c0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
234d0 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
234e0 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
234f0 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
23500 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
23510 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
23520 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
23530 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
23540 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
23550 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
23560 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
23570 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
23580 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
23590 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
235a0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
235b0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
235c0 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
235d0 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
235e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
235f0 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
23600 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
23610 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
23620 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
23630 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
23640 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
23650 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
23660 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
23670 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
23680 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
23690 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
236a0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
236b0 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
236c0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
236d0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
236e0 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
236f0 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
23700 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
23710 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
23720 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
23730 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
23740 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
23750 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
23760 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
23770 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
23780 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
23790 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
237a0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
237b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
237c0 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
237d0 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
237e0 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
237f0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
23800 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
23810 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
23820 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
23830 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
23840 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
23850 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
23860 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
23870 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
23880 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
23890 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
238a0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
238b0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
238c0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
238d0 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
238e0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
238f0 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
23900 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
23910 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
23920 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
23930 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
23940 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
23950 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
23960 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
23970 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
23980 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
23990 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
239a0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
239b0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
239c0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
239d0 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
239e0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
239f0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
23a00 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
23a10 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
23a20 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
23a30 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
23a40 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
23a50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
23a60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
23a70 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
23a80 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
23a90 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
23aa0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
23ab0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
23ac0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
23ad0 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
23ae0 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
23af0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
23b00 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
23b10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
23b20 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
23b30 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
23b40 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
23b50 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
23b60 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
23b70 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
23b80 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
23b90 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
23ba0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
23bb0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
23bc0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
23bd0 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
23be0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
23bf0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
23c00 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
23c10 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
23c20 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
23c30 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
23c40 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
23c50 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
23c60 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
23c70 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
23c80 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
23c90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
23ca0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
23cb0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
23cc0 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
23cd0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
23ce0 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
23cf0 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
23d00 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
23d10 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
23d20 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
23d30 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
23d40 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
23d50 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
23d60 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
23d70 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
23d80 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
23d90 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
23da0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
23db0 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
23dc0 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
23dd0 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
23de0 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
23df0 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
23e00 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
23e10 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
23e20 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
23e30 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
23e40 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
23e50 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
23e60 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
23e70 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
23e80 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
23e90 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
23ea0 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
23eb0 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
23ec0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
23ed0 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
23ee0 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
23ef0 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
23f00 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
23f10 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
23f20 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
23f30 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
23f40 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
23f50 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
23f60 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
23f70 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
23f80 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
23f90 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
23fa0 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
23fb0 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
23fc0 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
23fd0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
23fe0 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
23ff0 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
24000 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
24010 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
24020 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
24030 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
24040 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
24050 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
24060 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
24070 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
24080 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
24090 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
240a0 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
240b0 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
240c0 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
240d0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
240e0 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
240f0 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
24100 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
24110 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
24120 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
24130 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
24140 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
24150 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
24160 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
24170 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
24180 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
24190 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
241a0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
241b0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
241c0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
241d0 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
241e0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
241f0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
24200 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
24210 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
24220 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
24230 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
24240 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
24250 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
24260 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
24270 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
24280 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
24290 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
242a0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
242b0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
242c0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
242d0 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
242e0 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
242f0 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
24300 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
24310 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
24320 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
24330 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
24340 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
24350 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
24360 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
24370 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
24380 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
24390 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
243a0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
243b0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
243c0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
243d0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
243e0 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
243f0 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
24400 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
24410 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
24420 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
24430 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
24440 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
24450 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
24460 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
24470 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
24480 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
24490 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
244a0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
244b0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
244c0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
244d0 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
244e0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
244f0 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
24500 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
24510 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
24520 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
24530 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
24540 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
24550 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
24560 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
24570 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
24580 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
24590 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
245a0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
245b0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
245c0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
245d0 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
245e0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
245f0 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
24600 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
24610 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
24620 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
24630 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
24640 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
24650 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
24660 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
24670 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
24680 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
24690 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
246a0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
246b0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
246c0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
246d0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
246e0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
246f0 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
24700 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
24710 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
24720 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24730 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
24740 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
24750 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
24760 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24770 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
24780 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
24790 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
247a0 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
247b0 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
247c0 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
247d0 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
247e0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
247f0 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
24800 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
24810 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
24820 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
24830 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
24840 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
24850 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
24860 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
24870 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
24880 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
24890 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
248a0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
248b0 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
248c0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
248d0 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
248e0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
248f0 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
24900 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
24910 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
24920 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
24930 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
24940 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
24950 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
24960 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
24970 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
24980 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
24990 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
249a0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
249b0 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
249c0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
249d0 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
249e0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
249f0 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
24a00 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
24a10 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
24a20 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
24a30 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
24a40 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
24a50 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
24a60 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
24a70 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
24a80 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
24a90 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
24aa0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
24ab0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
24ac0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
24ad0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
24ae0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
24af0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24b00 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
24b10 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
24b20 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
24b30 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
24b40 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
24b50 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
24b60 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
24b70 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
24b80 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
24b90 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
24ba0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
24bb0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
24bc0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
24bd0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
24be0 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
24bf0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
24c00 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
24c10 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
24c20 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
24c30 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
24c40 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
24c50 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
24c60 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
24c70 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
24c80 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
24c90 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
24ca0 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
24cb0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
24cc0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
24cd0 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
24ce0 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
24cf0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
24d00 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
24d10 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
24d20 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
24d30 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
24d40 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
24d50 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
24d60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
24d70 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
24d80 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
24d90 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24da0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
24db0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
24dc0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
24dd0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
24de0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
24df0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
24e00 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
24e10 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
24e20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
24e30 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
24e40 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
24e50 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
24e60 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
24e70 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
24e80 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
24e90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
24ea0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
24eb0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
24ec0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
24ed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
24ee0 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
24ef0 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
24f00 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
24f10 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
24f20 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
24f30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
24f40 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
24f50 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
24f60 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
24f70 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
24f80 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
24f90 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
24fa0 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
24fb0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
24fc0 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
24fd0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
24fe0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
24ff0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
25000 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
25010 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
25020 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
25030 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
25040 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
25050 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
25060 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
25070 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
25080 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
25090 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
250a0 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
250b0 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
250c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
250d0 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
250e0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
250f0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
25100 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
25110 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
25120 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
25130 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
25140 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
25150 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
25160 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
25170 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
25180 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
25190 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
251a0 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
251b0 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
251c0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
251d0 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
251e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
251f0 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
25200 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25210 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
25220 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
25230 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
25240 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
25250 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
25260 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
25270 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
25280 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
25290 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
252a0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
252b0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
252c0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
252d0 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
252e0 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
252f0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
25300 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
25310 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
25320 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
25330 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
25340 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
25350 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
25360 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
25370 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
25380 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
25390 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
253a0 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
253b0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
253c0 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
253d0 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
253e0 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
253f0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
25400 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
25410 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
25420 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
25430 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
25440 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
25450 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
25460 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
25470 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
25480 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
25490 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
254a0 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
254b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
254c0 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
254d0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
254e0 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
254f0 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
25500 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
25510 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
25520 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
25530 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
25540 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
25550 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
25560 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
25570 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
25580 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
25590 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
255a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
255b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
255c0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
255d0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
255e0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
255f0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
25600 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
25610 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
25620 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
25630 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
25640 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
25650 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
25660 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
25670 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
25680 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
25690 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
256a0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
256b0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
256c0 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
256d0 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
256e0 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
256f0 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
25700 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
25710 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
25720 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
25730 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
25740 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
25750 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
25760 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
25770 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
25780 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
25790 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
257a0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
257b0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
257c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
257d0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
257e0 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ssages.** METHOD
257f0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
25800 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
25810 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ent sqlite3_* AP
25820 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
25830 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61  d with .** [data
25840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25850 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20   D failed, then 
25860 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  the sqlite3_errc
25870 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65  ode(D) interface
25880 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
25890 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
258a0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
258b0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
258c0 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20  for that.** API 
258d0 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20  call..** If the 
258e0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
258f0 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73  call was success
25900 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ful,.** then the
25910 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
25920 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
25930 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
25940 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
25950 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
25960 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
25970 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
25980 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
25990 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
259a0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
259b0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
259c0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
259d0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
259e0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
259f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25a00 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
25a10 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
25a20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
25a30 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
25a40 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
25a50 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
25a60 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
25a70 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
25a80 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
25a90 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
25aa0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
25ab0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
25ac0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
25ad0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
25ae0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
25af0 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
25b00 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
25b10 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
25b20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
25b30 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
25b40 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
25b50 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
25b60 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
25b70 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
25b80 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
25b90 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
25ba0 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
25bb0 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
25bc0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
25bd0 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
25be0 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
25bf0 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
25c00 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
25c10 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
25c20 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
25c30 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
25c40 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
25c50 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
25c60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
25c70 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
25c80 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
25c90 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
25ca0 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
25cb0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
25cc0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
25cd0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
25ce0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
25cf0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
25d00 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
25d10 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
25d20 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
25d30 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
25d40 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
25d50 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
25d60 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
25d70 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
25d80 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
25d90 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
25da0 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
25db0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
25dc0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
25dd0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
25de0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
25df0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
25e00 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
25e10 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
25e20 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
25e30 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
25e40 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
25e50 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
25e60 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
25e70 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
25e80 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
25e90 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
25ea0 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
25eb0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
25ec0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
25ed0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
25ee0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
25ef0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
25f00 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
25f10 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
25f20 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
25f30 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
25f40 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
25f50 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
25f60 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
25f70 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
25f80 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
25f90 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
25fa0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
25fb0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
25fc0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
25fd0 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
25fe0 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
25ff0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
26000 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
26010 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
26020 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
26030 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68  ite3*);.const ch
26040 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
26050 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
26060 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
26070 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
26080 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
26090 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
260a0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
260b0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
260c0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
260d0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
260e0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
260f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
26100 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  hat.** has been 
26110 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69  compiled into bi
26120 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73  nary form and is
26130 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61   ready to be eva
26140 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  luated..**.** Th
26150 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20  ink of each SQL 
26160 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73  statement as a s
26170 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72  eparate computer
26180 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a   program.  The.*
26190 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
261a0 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f  ext is source co
261b0 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20  de.  A prepared 
261c0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
261d0 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70   .** is the comp
261e0 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65  iled object code
261f0 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20  .  All SQL must 
26200 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  be converted int
26210 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  o a.** prepared 
26220 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65  statement before
26230 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a   it can be run..
26240 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63  **.** The life-c
26250 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72  ycle of a prepar
26260 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
26270 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73  ect usually goes
26280 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
26290 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
262a0 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72  reate the prepar
262b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
262c0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
262d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
262e0 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
262f0 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65  alues to [parame
26300 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
26310 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
26320 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
26330 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
26340 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
26350 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
26360 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
26370 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
26380 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  Reset the prepar
26390 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
263a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
263b0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
263c0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
263d0 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
263e0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
263f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
26400 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
26410 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
26420 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
26430 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  >.*/.typedef str
26440 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
26450 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
26460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26470 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
26480 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
26490 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e3.**.** ^(This 
264a0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
264b0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
264c0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
264d0 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
264e0 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
264f0 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
26500 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
26510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
26520 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
26530 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
26540 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
26550 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
26560 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
26570 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
26580 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
26590 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
265a0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
265b0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
265c0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
265d0 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
265e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
265f0 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
26600 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
26610 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
26620 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
26630 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
26640 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
26650 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
26660 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
26670 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
26680 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
26690 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
266a0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
266b0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
266c0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
266d0 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
266e0 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
266f0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
26700 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
26710 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
26720 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
26730 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
26740 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
26750 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
26760 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
26770 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
26780 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
26790 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
267a0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
267b0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
267c0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
267d0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
267e0 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
267f0 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
26800 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
26810 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
26820 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
26830 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
26840 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
26850 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
26860 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
26870 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
26880 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
26890 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
268a0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
268b0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
268c0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
268d0 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
268e0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
268f0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
26900 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
26910 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
26920 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
26930 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
26940 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
26950 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
26960 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
26970 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
26980 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
26990 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
269a0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
269b0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
269c0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
269d0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
269e0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
269f0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
26a00 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
26a10 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
26a20 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
26a30 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
26a40 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
26a50 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
26a60 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
26a70 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
26a80 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
26a90 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
26aa0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
26ab0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
26ac0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
26ad0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
26ae0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
26af0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
26b00 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
26b10 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
26b20 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
26b30 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
26b40 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
26b50 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
26b60 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
26b70 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
26b80 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
26b90 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
26ba0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
26bb0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
26bc0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
26bd0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
26be0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
26bf0 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
26c00 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
26c10 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
26c20 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
26c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
26c40 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
26c50 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
26c60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26c70 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
26c80 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
26c90 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
26ca0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
26cb0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
26cc0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
26cd0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
26ce0 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
26cf0 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
26d00 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
26d10 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
26d20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
26d30 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
26d40 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
26d50 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
26d60 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
26d70 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
26d80 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
26d90 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
26da0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
26db0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
26dc0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
26dd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
26de0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
26df0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
26e00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26e10 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
26e20 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
26e30 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
26e40 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
26e50 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26e60 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
26e70 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26e80 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
26e90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26ea0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
26eb0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
26ec0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
26ed0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26ee0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
26ef0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26f00 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
26f10 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26f20 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
26f30 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
26f40 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
26f50 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
26f60 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
26f70 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
26f80 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
26f90 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
26fa0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
26fb0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
26fc0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
26fd0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26fe0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
26ff0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27000 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
27010 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27020 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
27030 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
27040 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
27050 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
27060 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
27070 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
27080 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
27090 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
270a0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
270b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
270c0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
270d0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
270e0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
270f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
27100 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
27110 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27120 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
27130 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
27140 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
27150 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
27160 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
27170 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
27180 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
27190 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
271a0 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
271b0 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
271c0 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
271d0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
271e0 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
271f0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
27200 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
27210 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27220 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
27230 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
27240 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
27250 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
27260 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
27270 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
27280 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
27290 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
272a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
272b0 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
272c0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
272d0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
272e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
272f0 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
27300 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
27310 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
27320 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27330 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
27340 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
27350 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
27360 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
27370 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27380 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
27390 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
273a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
273b0 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
273c0 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
273d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
273e0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
273f0 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
27400 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
27410 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
27420 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27430 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
27440 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
27450 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
27460 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
27470 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27480 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
27490 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
274a0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
274b0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
274c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
274d0 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
274e0 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
274f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
27500 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
27510 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64  R_THREADS]] ^(<d
27520 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  t>SQLITE_LIMIT_W
27530 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64  ORKER_THREADS</d
27540 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
27550 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
27560 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72  auxiliary worker
27570 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20   threads that a 
27580 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61  single.** [prepa
27590 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d  red statement] m
275a0 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e  ay start.</dd>)^
275b0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
275c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
275d0 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
275e0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
275f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27600 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
27610 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
27620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27630 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
27640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
27650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27660 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
27670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
27680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27690 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
276a0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
276b0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
276c0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
276d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
276e0 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
276f0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
27700 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
27710 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
27720 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
27730 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
27740 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
27750 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
27760 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
27770 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
27780 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
27790 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
277a0 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
277b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
277c0 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
277d0 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
277e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
277f0 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20  KER_THREADS     
27800 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20        11../*.** 
27810 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
27820 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
27830 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
27840 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
27850 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45   compiler}.** ME
27860 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
27870 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
27880 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
27890 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
278a0 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
278b0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
278c0 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
278d0 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
278e0 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
278f0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
27900 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
27910 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
27920 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
27930 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
27940 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
27950 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
27960 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
27970 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
27980 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
27990 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
279a0 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
279b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
279c0 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
279d0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
279e0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
279f0 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
27a00 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
27a10 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
27a20 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
27a30 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
27a40 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
27a50 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
27a60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
27a70 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
27a80 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
27a90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27aa0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
27ab0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
27ac0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
27ad0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
27ae0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67   argument is neg
27af0 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c  ative, then zSql
27b00 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
27b10 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
27b20 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
27b30 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69   nByte is positi
27b40 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
27b50 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
27b60 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
27b70 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65  zSql.  ^If nByte
27b80 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e   is zero, then n
27b90 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  o prepared.** st
27ba0 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72  atement is gener
27bb0 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ated..** If the 
27bc0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61  caller knows tha
27bd0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
27be0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
27bf0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a  minated, then.**
27c00 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
27c10 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  l performance ad
27c20 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69  vantage to passi
27c30 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
27c40 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
27c50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
27c60 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
27c70 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
27c80 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
27c90 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e   nul-terminator.
27ca0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
27cb0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
27cc0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
27cd0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
27ce0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
27cf0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
27d00 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
27d10 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
27d20 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
27d30 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
27d40 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
27d50 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
27d60 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
27d70 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
27d80 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
27d90 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
27da0 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
27db0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
27dc0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
27dd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
27de0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
27df0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
27e00 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
27e10 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
27e20 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
27e30 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
27e40 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
27e50 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
27e60 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
27e70 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
27e80 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
27e90 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
27ea0 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
27eb0 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
27ec0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
27ed0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
27ee0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
27ef0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
27f00 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
27f10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
27f20 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
27f30 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
27f40 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
27f50 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
27f60 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
27f70 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
27f80 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
27f90 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
27fa0 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
27fb0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
27fc0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
27fd0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
27fe0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
27ff0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
28000 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
28010 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
28020 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
28030 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
28040 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
28050 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
28060 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
28070 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
28080 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
28090 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
280a0 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
280b0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
280c0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
280d0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
280e0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
280f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
28100 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
28110 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
28120 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
28130 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
28140 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
28150 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
28160 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
28170 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
28180 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
28190 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
281a0 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
281b0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
281c0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
281d0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
281e0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
281f0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
28200 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
28210 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
28220 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
28230 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
28240 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
28250 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
28260 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
28270 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
28280 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
28290 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
282a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
282b0 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
282c0 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
282d0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
282e0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
282f0 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
28300 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
28310 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
28320 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
28330 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
28340 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
28350 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
28360 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
28370 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
28380 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
28390 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
283a0 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
283b0 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
283c0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
283d0 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
283e0 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
283f0 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
28400 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
28410 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
28420 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
28430 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
28440 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
28450 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
28460 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
28470 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
28480 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
28490 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
284a0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
284b0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
284c0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
284d0 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
284e0 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
284f0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
28500 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
28510 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
28520 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
28530 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
28540 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
28550 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
28560 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
28570 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
28580 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
28590 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
285a0 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
285b0 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
285c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
285d0 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
285e0 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
285f0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
28600 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
28610 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
28620 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
28630 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
28640 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
28650 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
28660 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
28670 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
28680 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
28690 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
286a0 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
286b0 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
286c0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
286d0 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
286e0 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
286f0 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
28700 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
28710 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
28720 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
28730 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
28740 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c   enabled..** </l
28750 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
28760 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
28770 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
28780 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
28790 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
287a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
287b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
287c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
287d0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
287e0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
287f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28800 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
28810 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
28820 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
28830 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28840 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
28850 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28860 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
28870 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28880 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28890 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
288a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
288b0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
288c0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
288d0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
288e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
288f0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
28900 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
28910 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
28920 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
28930 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
28940 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
28950 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
28960 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
28970 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
28980 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
28990 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
289a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
289b0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
289c0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
289d0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
289e0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
289f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
28a00 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28a10 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28a20 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28a30 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
28a40 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
28a50 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
28a60 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
28a70 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
28a80 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
28a90 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
28aa0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
28ab0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
28ac0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28ad0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28ae0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
28af0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28b00 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28b10 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28b20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
28b30 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
28b40 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
28b50 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
28b60 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
28b70 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28b80 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
28b90 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
28ba0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
28bb0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
28bc0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
28bd0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
28be0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
28bf0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
28c00 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
28c10 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
28c20 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
28c30 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
28c40 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
28c50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
28c60 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
28c70 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
28c80 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
28c90 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
28ca0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
28cb0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
28cc0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
28cd0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
28ce0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
28cf0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
28d00 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
28d10 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
28d20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28d30 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
28d40 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
28d50 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
28d60 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
28d70 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
28d80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28d90 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
28da0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28db0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
28dc0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
28dd0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
28de0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
28df0 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
28e00 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20  The Database.** 
28e10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
28e20 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
28e30 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
28e40 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
28e50 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
28e60 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
28e70 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
28e80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28e90 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
28ea0 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
28eb0 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
28ec0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
28ed0 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
28ee0 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
28ef0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
28f00 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
28f10 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
28f20 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
28f30 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
28f40 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
28f50 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
28f60 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
28f70 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
28f80 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
28f90 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
28fa0 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
28fb0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
28fc0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
28fd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
28fe0 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
28ff0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
29000 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
29010 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
29020 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
29030 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
29040 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
29050 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
29060 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
29070 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
29080 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
29090 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
290a0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
290b0 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
290c0 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
290d0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
290e0 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
290f0 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
29100 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
29110 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
29120 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
29130 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
29140 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
29150 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
29160 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
29170 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
29180 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
29190 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
291a0 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
291b0 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
291c0 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
291d0 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
291e0 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
291f0 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
29200 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
29210 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
29220 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
29230 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
29240 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
29250 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
29260 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
29270 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
29280 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
29290 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
292a0 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
292b0 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
292c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
292d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
292e0 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
292f0 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
29300 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
29310 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
29320 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
29330 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
29340 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
29350 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
29360 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29370 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
29380 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
29390 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
293a0 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eset.** METHOD: 
293b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
293c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
293d0 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
293e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
293f0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
29400 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
29410 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
29420 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
29430 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
29440 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
29450 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
29460 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74  as neither run t
29470 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65  o completion (re
29480 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
29490 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71  E_DONE] from [sq
294a0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20  lite3_step(S)]) 
294b0 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  nor.** been rese
294c0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
294d0 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
294e0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
294f0 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
29500 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
29510 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
29520 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
29530 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
29540 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
29550 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
29560 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
29570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
29580 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
29590 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
295a0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
295b0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
295c0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
295d0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
295e0 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
295f0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
29600 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
29610 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
29620 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
29630 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
29640 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
29650 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
29660 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
29670 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
29680 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
29690 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
296a0 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
296b0 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
296c0 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
296d0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
296e0 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
296f0 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
29700 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
29710 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
29720 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
29730 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
29740 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
29750 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
29760 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
29770 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
29780 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
29790 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
297a0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
297b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
297c0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
297d0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
297e0 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
297f0 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
29800 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
29810 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
29820 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
29830 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
29840 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
29850 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
29860 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
29870 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
29880 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
29890 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
298a0 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
298b0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
298c0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
298d0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
298e0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
298f0 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
29900 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
29910 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
29920 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
29930 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
29940 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
29950 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
29960 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
29970 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29980 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
29990 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
299a0 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
299b0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
299c0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
299d0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
299e0 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
299f0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68  lite3_value.  Th
29a00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  e.** [sqlite3_va
29a10 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72  lue_dup()] inter
29a20 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
29a30 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20   to construct a 
29a40 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65  new .** protecte
29a50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
29a60 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63  from an unprotec
29a70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29a80 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
29a90 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
29aa0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
29ab0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
29ac0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
29ad0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
29ae0 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
29af0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
29b00 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
29b10 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
29b20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
29b30 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
29b40 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
29b50 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
29b60 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
29b70 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
29b80 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
29b90 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
29ba0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
29bb0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
29bc0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
29bd0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
29be0 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
29bf0 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
29c00 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
29c10 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
29c20 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
29c30 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
29c40 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
29c50 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
29c60 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
29c70 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
29c80 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
29c90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
29ca0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
29cb0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
29cc0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
29cd0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
29ce0 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
29cf0 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
29d00 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
29d10 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
29d20 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
29d30 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
29d40 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
29d50 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
29d60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29d70 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
29d80 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
29d90 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
29da0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
29db0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
29dc0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
29dd0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
29de0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
29df0 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
29e00 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
29e10 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
29e20 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
29e30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29e40 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
29e50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
29e60 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
29e70 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
29e80 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
29e90 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29ea0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
29eb0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
29ec0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
29ed0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
29ee0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
29ef0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
29f00 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
29f10 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
29f20 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
29f30 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
29f40 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
29f50 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29f60 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
29f70 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
29f80 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
29f90 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
29fa0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
29fb0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
29fc0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
29fd0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
29fe0 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
29ff0 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
2a000 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2a010 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
2a020 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
2a030 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
2a040 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
2a050 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
2a060 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a070 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2a080 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
2a090 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2a0a0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2a0b0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
2a0c0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
2a0d0 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
2a0e0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2a0f0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
2a100 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
2a110 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
2a120 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2a130 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
2a140 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
2a150 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2a160 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
2a170 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2a180 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
2a190 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2a1a0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
2a1b0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2a1c0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
2a1d0 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
2a1e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
2a1f0 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
2a200 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2a210 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
2a220 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2a230 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2a240 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
2a250 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
2a260 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
2a270 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
2a280 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
2a290 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d  er binding}.** M
2a2a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2a2b0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  tmt.**.** ^(In t
2a2c0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2a2d0 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
2a2e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a2f0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
2a300 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
2a310 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
2a320 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
2a330 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
2a340 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
2a350 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
2a360 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2a370 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
2a380 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
2a390 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
2a3a0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
2a3b0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2a3c0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
2a3d0 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
2a3e0 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
2a3f0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
2a400 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
2a410 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
2a420 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
2a430 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
2a440 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
2a450 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
2a460 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2a470 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
2a480 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
2a490 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
2a4a0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2a4b0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
2a4c0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
2a4d0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2a4e0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
2a4f0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2a500 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
2a510 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
2a520 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2a530 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2a540 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
2a550 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2a560 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
2a570 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2a580 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2a590 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2a5a0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
2a5b0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
2a5c0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
2a5d0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2a5e0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
2a5f0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
2a600 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
2a610 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
2a620 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
2a630 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2a640 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
2a650 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
2a660 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
2a670 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
2a680 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
2a690 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
2a6a0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
2a6b0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
2a6c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a6d0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
2a6e0 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
2a6f0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
2a700 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
2a710 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
2a720 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
2a730 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
2a740 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
2a750 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
2a760 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
2a770 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
2a780 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2a790 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
2a7a0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
2a7b0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2a7c0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
2a7d0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
2a7e0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
2a7f0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2a800 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2a810 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2a820 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a830 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
2a840 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2a850 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2a860 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2a870 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
2a880 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
2a890 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
2a8a0 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
2a8b0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
2a8c0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
2a8d0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
2a8e0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
2a8f0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
2a900 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2a910 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2a920 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
2a930 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
2a940 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2a950 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
2a960 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
2a970 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
2a980 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2a990 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
2a9a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2a9b0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a9c0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2a9d0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2a9e0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
2a9f0 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
2aa00 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
2aa10 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2aa20 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
2aa30 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
2aa40 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
2aa50 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2aa60 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2aa70 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
2aa80 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
2aa90 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2aaa0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2aab0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
2aac0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2aad0 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
2aae0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2aaf0 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
2ab00 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
2ab10 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2ab20 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a  text64() then.**
2ab30 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
2ab40 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
2ab50 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
2ab60 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
2ab70 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
2ab80 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
2ab90 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
2aba0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
2abb0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
2abc0 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
2abd0 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
2abe0 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
2abf0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2ac00 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
2ac10 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
2ac20 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
2ac30 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
2ac40 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
2ac50 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
2ac60 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
2ac70 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
2ac80 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
2ac90 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2aca0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
2acb0 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61  nt to the BLOB a
2acc0 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e  nd string bindin
2acd0 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  g interfaces.** 
2ace0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2acf0 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
2ad00 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
2ad10 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
2ad20 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
2ad30 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
2ad40 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2ad50 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
2ad60 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2ad70 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
2ad80 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62  if the call to b
2ad90 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a  ind API fails..*
2ada0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2adb0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
2adc0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
2add0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
2ade0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
2adf0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
2ae00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
2ae10 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
2ae20 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
2ae30 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2ae40 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
2ae50 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2ae60 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
2ae70 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
2ae80 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
2ae90 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
2aea0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2aeb0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
2aec0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
2aed0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
2aee0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2aef0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2af00 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d  ^The sixth argum
2af10 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2af20 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73  ind_text64() mus
2af30 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b  t be one of.** [
2af40 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
2af50 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
2af60 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
2af70 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2af80 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66  LE].** to specif
2af90 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  y the encoding o
2afa0 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68  f the text in th
2afb0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2afc0 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69  r.  If.** the si
2afd0 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2afe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2aff0 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  t64() is not one
2b000 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77   of the.** allow
2b010 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20  ed values shown 
2b020 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65  above, or if the
2b030 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
2b040 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66  s different.** f
2b050 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  rom the encoding
2b060 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2b070 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
2b080 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  r, then the beha
2b090 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66  vior.** is undef
2b0a0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2b0b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2b0c0 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
2b0d0 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
2b0e0 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
2b0f0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
2b100 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
2b110 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
2b120 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
2b130 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
2b140 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
2b150 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
2b160 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
2b170 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
2b180 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
2b190 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
2b1a0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
2b1b0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
2b1c0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
2b1d0 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
2b1e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
2b1f0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
2b200 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
2b210 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
2b220 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
2b230 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
2b240 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
2b250 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
2b260 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
2b270 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2b280 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2b290 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
2b2a0 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
2b2b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b2c0 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
2b2d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b2e0 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
2b2f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b300 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
2b310 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
2b320 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
2b330 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
2b340 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
2b350 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
2b360 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
2b370 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
2b380 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
2b390 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
2b3a0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2b3b0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2b3c0 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
2b3d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2b3e0 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
2b3f0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
2b400 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
2b410 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
2b420 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
2b430 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
2b440 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
2b450 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
2b460 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2b470 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
2b480 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2b490 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2b4a0 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
2b4b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
2b4c0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
2b4d0 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
2b4e0 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62  _TOOBIG] might b
2b4f0 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
2b500 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69  e size of a stri
2b510 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78  ng or BLOB.** ex
2b520 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70  ceeds limits imp
2b530 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
2b540 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2b550 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f  LIMIT_LENGTH]) o
2b560 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  r.** [SQLITE_MAX
2b570 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53  _LENGTH]..** ^[S
2b580 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
2b590 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2b5a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
2b5b0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2b5c0 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
2b5d0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
2b5e0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
2b5f0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
2b600 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2b610 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2b620 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2b630 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b640 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
2b650 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b660 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2b670 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2b680 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
2b690 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2b6a0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
2b6b0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2b6c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2b6d0 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
2b6e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b6f0 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
2b700 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2b710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b720 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2b730 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2b740 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
2b750 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b760 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
2b770 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
2b780 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b790 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
2b7a0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
2b7b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b7c0 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
2b7d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b7e0 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
2b7f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
2b800 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2b810 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2b820 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
2b830 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  *,int,void(*)(vo
2b840 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2b850 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
2b860 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b870 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2b880 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2b890 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2b8a0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71  3_bind_text64(sq
2b8b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b8c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
2b8d0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2b8e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b8f0 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2b900 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
2b910 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
2b920 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2b930 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
2b940 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2b950 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
2b960 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b970 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
2b980 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2b990 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c   int n);.int sql
2b9a0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2b9b0 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2b9c0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2b9d0 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  _uint64);../*.**
2b9e0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2b9f0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
2ba00 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ers.** METHOD: s
2ba10 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ba20 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
2ba30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
2ba40 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
2ba50 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
2ba60 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
2ba70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2ba80 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
2ba90 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
2baa0 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
2bab0 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
2bac0 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
2bad0 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
2bae0 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
2baf0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
2bb00 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
2bb10 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
2bb20 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
2bb30 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
2bb40 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
2bb50 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
2bb60 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
2bb70 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
2bb80 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
2bb90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
2bba0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
2bbb0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
2bbc0 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
2bbd0 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
2bbe0 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
2bbf0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
2bc00 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
2bc10 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
2bc20 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
2bc30 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
2bc40 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
2bc50 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2bc60 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2bc70 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2bc80 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2bc90 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
2bca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2bcb0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2bcc0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2bcd0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2bce0 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
2bcf0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2bd00 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
2bd10 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
2bd20 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  er.** METHOD: sq
2bd30 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2bd40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2bd50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2bd60 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
2bd70 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2bd80 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
2bd90 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
2bda0 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
2bdb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2bdc0 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
2bdd0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2bde0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2bdf0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2be00 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
2be10 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
2be20 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
2be30 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2be40 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2be50 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2be60 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2be70 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
2be80 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
2be90 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
2bea0 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
2beb0 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
2bec0 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
2bed0 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
2bee0 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
2bef0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
2bf00 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
2bf10 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
2bf20 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
2bf30 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
2bf40 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
2bf50 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
2bf60 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2bf70 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
2bf80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
2bf90 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
2bfa0 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
2bfb0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
2bfc0 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
2bfd0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
2bfe0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2bff0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
2c000 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
2c010 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
2c020 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
2c030 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
2c040 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
2c050 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
2c060 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c070 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2c080 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c090 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2c0a0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2c0b0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2c0c0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2c0d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2c0e0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
2c0f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2c100 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2c110 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
2c120 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
2c130 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2c140 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c150 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2c160 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
2c170 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
2c180 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
2c190 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2c1a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
2c1b0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
2c1c0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
2c1d0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
2c1e0 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
2c1f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2c200 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
2c210 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
2c220 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
2c230 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
2c240 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2c250 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
2c260 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
2c270 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
2c280 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
2c290 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
2c2a0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
2c2b0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
2c2c0 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
2c2d0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
2c2e0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
2c2f0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
2c300 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
2c310 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2c320 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2c330 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2c340 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2c350 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2c360 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2c370 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2c380 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2c390 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e  rameter_name()].
2c3a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c3b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2c3c0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
2c3d0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
2c3e0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
2c3f0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2c400 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
2c410 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2c420 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
2c430 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c440 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
2c450 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
2c460 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
2c470 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
2c480 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
2c490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c4a0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
2c4b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2c4c0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
2c4d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
2c4e0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
2c4f0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
2c500 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
2c510 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2c520 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2c530 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c540 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
2c550 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
2c560 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
2c570 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c580 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
2c590 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2c5a0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2c5b0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
2c5c0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2c5d0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
2c5e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2c5f0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
2c600 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
2c610 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
2c620 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
2c630 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
2c640 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
2c650 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2c660 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
2c670 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2c680 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
2c690 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2c6a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c6b0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
2c6c0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2c6d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c6e0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2c6f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2c700 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2c710 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2c720 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2c730 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2c740 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2c750 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2c760 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c770 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2c780 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2c790 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2c7a0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2c7b0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2c7c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2c7d0 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2c7e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2c7f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2c800 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2c810 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2c820 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2c830 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c840 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2c850 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2c860 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2c870 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2c880 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2c890 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2c8a0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2c8b0 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2c8c0 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2c8d0 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2c8e0 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2c8f0 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2c900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c910 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2c920 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2c930 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2c940 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2c950 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2c960 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2c970 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2c980 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2c990 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2c9a0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2c9b0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2c9c0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2c9d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2c9e0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2c9f0 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2ca00 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2ca10 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2ca20 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2ca30 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2ca40 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2ca50 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2ca60 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2ca70 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2ca80 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2ca90 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2caa0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2cab0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2cac0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2cad0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2cae0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2caf0 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2cb00 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2cb10 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2cb20 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2cb30 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2cb40 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2cb50 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2cb60 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2cb70 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2cb80 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2cb90 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2cba0 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
2cbb0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2cbc0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2cbd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2cbe0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2cbf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2cc00 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2cc10 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2cc20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2cc30 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2cc40 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2cc50 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2cc60 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2cc70 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2cc80 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2cc90 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2cca0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2ccb0 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2ccc0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2ccd0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2cce0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2ccf0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2cd00 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2cd10 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2cd20 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2cd30 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2cd40 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2cd50 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2cd60 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2cd70 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2cd80 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2cd90 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2cda0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2cdb0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2cdc0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2cdd0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2cde0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2cdf0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2ce00 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2ce10 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2ce20 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2ce30 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2ce40 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2ce50 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2ce60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2ce70 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2ce80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2ce90 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2cea0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2ceb0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2cec0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ced0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2cee0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2cef0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2cf00 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2cf10 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2cf20 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2cf30 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2cf40 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2cf50 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2cf60 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2cf70 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2cf80 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2cf90 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2cfa0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2cfb0 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2cfc0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2cfd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cfe0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2cff0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2d000 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2d010 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2d020 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2d030 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2d040 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2d050 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2d060 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2d070 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2d080 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2d090 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2d0a0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2d0b0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2d0c0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2d0d0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2d0e0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2d0f0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2d100 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2d110 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2d120 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2d130 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2d140 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2d150 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2d160 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2d170 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2d180 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2d190 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2d1a0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2d1b0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2d1c0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2d1d0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2d1e0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2d1f0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2d200 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2d210 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2d220 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2d230 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2d240 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2d250 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2d260 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2d270 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2d280 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2d290 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2d2a0 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2d2b0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2d2c0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2d2d0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2d2e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2d2f0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2d300 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2d310 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2d320 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2d330 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2d340 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2d350 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2d360 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2d370 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d380 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2d390 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2d3a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2d3b0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2d3c0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2d3d0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2d3e0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2d3f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2d400 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2d410 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2d420 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2d430 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2d440 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d450 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2d460 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2d470 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2d480 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2d490 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
2d4a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2d4b0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2d4c0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2d4d0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2d4e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2d4f0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2d500 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2d510 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2d520 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2d530 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2d540 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d550 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2d560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d570 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2d580 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d590 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2d5a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2d5b0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2d5c0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2d5d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2d5e0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2d5f0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2d600 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2d610 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2d620 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2d630 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
2d640 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2d650 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  stmt.**.** ^(The
2d660 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2d670 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2d680 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2d690 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
2d6a0 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
2d6b0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
2d6c0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2d6d0 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
2d6e0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
2d6f0 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
2d700 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
2d710 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
2d720 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
2d730 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
2d740 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
2d750 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
2d760 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
2d770 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2d780 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2d790 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
2d7a0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2d7b0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
2d7c0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2d7d0 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
2d7e0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2d7f0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
2d800 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
2d810 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
2d820 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2d830 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
2d840 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
2d850 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
2d860 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
2d870 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2d880 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
2d890 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
2d8a0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
2d8b0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
2d8c0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
2d8d0 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
2d8e0 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
2d8f0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
2d900 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
2d910 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
2d920 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
2d930 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
2d940 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2d950 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
2d960 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
2d970 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
2d980 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
2d990 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
2d9a0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2d9b0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
2d9c0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
2d9d0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
2d9e0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
2d9f0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2da00 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
2da10 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
2da20 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
2da30 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
2da40 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
2da50 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
2da60 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
2da70 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
2da80 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
2da90 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
2daa0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
2dab0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2dac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2dad0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2dae0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2daf0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2db00 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
2db10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2db20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2db30 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
2db40 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2db50 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2db60 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  stmt.**.** After
2db70 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2db80 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2db90 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2dba0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2dbb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2dbc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2dbd0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2dbe0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2dbf0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2dc00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2dc10 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2dc20 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2dc30 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2dc40 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2dc50 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2dc60 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2dc70 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2dc80 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2dc90 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2dca0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2dcb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2dcc0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2dcd0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2dce0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2dcf0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2dd00 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2dd10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2dd20 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2dd30 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2dd40 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2dd50 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2dd60 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2dd70 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2dd80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2dd90 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2dda0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2ddb0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2ddc0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2ddd0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2dde0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2ddf0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2de00 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2de10 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2de20 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2de30 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2de40 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2de50 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2de60 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2de70 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2de80 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2de90 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2dea0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2deb0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2dec0 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2ded0 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2dee0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2def0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2df00 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2df10 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2df20 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2df30 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2df40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2df50 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2df60 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2df70 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2df80 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2df90 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2dfa0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2dfb0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2dfc0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2dfd0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2dfe0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2dff0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2e000 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2e010 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2e020 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2e030 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2e040 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2e050 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2e060 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2e070 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2e080 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2e090 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2e0a0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2e0b0 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2e0c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2e0d0 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2e0e0 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2e0f0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2e100 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2e110 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2e120 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2e130 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2e140 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2e150 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2e160 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2e170 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2e180 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2e190 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2e1a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2e1b0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2e1c0 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2e1d0 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2e1e0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2e1f0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2e200 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2e210 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2e220 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2e230 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2e240 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2e250 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2e260 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2e270 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2e280 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2e290 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2e2a0 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2e2b0 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2e2c0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2e2d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2e2e0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2e2f0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2e300 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2e310 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2e320 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2e330 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2e340 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2e350 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2e360 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2e370 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2e380 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2e390 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2e3a0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2e3b0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2e3c0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2e3d0 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2e3e0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2e3f0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2e400 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2e410 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2e420 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2e430 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2e440 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2e450 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e460 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2e470 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2e480 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2e490 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2e4a0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2e4b0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2e4c0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2e4d0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2e4e0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2e4f0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2e500 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2e510 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2e520 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2e530 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2e540 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2e550 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e560 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2e570 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2e580 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2e590 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2e5a0 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2e5b0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2e5c0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2e5d0 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2e5e0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2e5f0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2e600 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2e610 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e620 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2e630 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2e640 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2e650 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2e660 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2e670 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2e680 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2e690 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2e6a0 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2e6b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2e6c0 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2e6d0 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2e6e0 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2e6f0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2e700 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2e710 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2e720 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2e730 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2e740 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2e750 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2e760 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2e770 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2e780 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e790 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2e7a0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2e7b0 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2e7c0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2e7d0 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2e7e0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2e7f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2e800 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2e810 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e820 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2e830 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2e840 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2e850 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2e860 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2e870 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2e880 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2e890 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2e8a0 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2e8b0 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2e8c0 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2e8d0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2e8e0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2e8f0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2e900 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2e910 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2e920 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2e930 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2e940 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2e950 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2e960 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2e970 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2e980 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2e990 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2e9a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2e9b0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2e9c0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2e9d0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2e9e0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2e9f0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2ea00 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2ea10 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2ea20 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2ea30 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2ea40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ea50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2ea60 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2ea70 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2ea80 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2ea90 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2eaa0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2eab0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2eac0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2ead0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2eae0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2eaf0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2eb00 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2eb10 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2eb20 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2eb30 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2eb40 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2eb50 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2eb60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2eb70 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2eb80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2eb90 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2eba0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2ebb0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2ebc0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2ebd0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2ebe0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2ebf0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2ec00 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2ec10 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2ec20 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2ec30 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2ec40 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2ec50 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2ec60 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
2ec70 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
2ec80 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2ec90 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2eca0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2ecb0 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
2ecc0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2ecd0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2ece0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2ecf0 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
2ed00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2ed10 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2ed20 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
2ed30 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2ed40 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
2ed50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2ed60 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
2ed70 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
2ed80 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
2ed90 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
2eda0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
2edb0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
2edc0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
2edd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
2ede0 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
2edf0 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
2ee00 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2ee10 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
2ee20 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2ee30 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2ee40 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
2ee50 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
2ee60 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
2ee70 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2ee80 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
2ee90 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
2eea0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
2eeb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2eec0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
2eed0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
2eee0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2eef0 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
2ef00 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
2ef10 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
2ef20 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2ef30 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
2ef40 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
2ef50 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
2ef60 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
2ef70 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
2ef80 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
2ef90 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
2efa0 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
2efb0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
2efc0 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
2efd0 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
2efe0 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
2eff0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2f000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2f010 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
2f020 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2f030 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2f040 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2f050 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
2f060 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
2f070 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
2f080 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
2f090 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
2f0a0 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
2f0b0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
2f0c0 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
2f0d0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2f0e0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2f0f0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
2f100 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
2f110 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
2f120 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
2f130 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
2f140 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
2f150 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
2f160 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
2f170 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
2f180 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
2f190 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
2f1a0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
2f1b0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
2f1c0 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
2f1d0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
2f1e0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
2f1f0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
2f200 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
2f210 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
2f220 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
2f230 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
2f240 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
2f250 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
2f260 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
2f270 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
2f280 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
2f290 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2f2a0 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
2f2b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
2f2c0 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
2f2d0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
2f2e0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
2f2f0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
2f300 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
2f310 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
2f320 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
2f330 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
2f340 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
2f350 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2f360 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
2f370 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
2f380 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
2f390 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
2f3a0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2f3b0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2f3c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2f3d0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2f3e0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
2f3f0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
2f400 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
2f410 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
2f420 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
2f430 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2f440 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
2f450 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
2f460 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2f470 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
2f480 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
2f490 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
2f4a0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2f4b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
2f4c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
2f4d0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
2f4e0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
2f4f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2f500 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2f510 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
2f520 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
2f530 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
2f540 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
2f550 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
2f560 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
2f570 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
2f580 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
2f590 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2f5a0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
2f5b0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
2f5c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2f5d0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
2f5e0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2f5f0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2f600 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
2f610 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
2f620 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
2f630 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
2f640 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
2f650 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2f660 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
2f670 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
2f680 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
2f690 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2f6a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2f6b0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2f6c0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2f6d0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
2f6e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2f6f0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
2f700 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
2f710 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
2f720 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
2f730 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
2f740 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2f750 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
2f760 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2f770 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2f780 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
2f790 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f7a0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
2f7b0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
2f7c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2f7d0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
2f7e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2f7f0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
2f800 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2f810 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2f820 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f830 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
2f840 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
2f850 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
2f860 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2f870 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
2f880 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2f890 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2f8a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2f8b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f8c0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2f8d0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2f8e0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2f8f0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2f900 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2f910 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2f920 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2f930 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2f940 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2f950 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2f960 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2f970 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2f980 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2f990 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2f9a0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2f9b0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2f9c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2f9d0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2f9e0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2f9f0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2fa00 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2fa10 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2fa20 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2fa30 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2fa40 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2fa50 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2fa60 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2fa70 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2fa80 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2fa90 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2faa0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2fab0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2fac0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2fad0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2fae0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2faf0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2fb00 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2fb10 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2fb20 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2fb30 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2fb40 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2fb50 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2fb60 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2fb70 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2fb80 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2fb90 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2fba0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2fbb0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2fbc0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2fbd0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2fbe0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2fbf0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2fc00 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2fc10 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2fc20 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2fc30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2fc40 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2fc50 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2fc60 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2fc70 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2fc80 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2fc90 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2fca0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2fcb0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2fcc0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2fcd0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2fce0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2fcf0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2fd00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2fd10 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2fd20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2fd30 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2fd40 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2fd50 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2fd60 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2fd70 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2fd80 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2fd90 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2fda0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2fdb0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2fdc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2fdd0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2fde0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2fdf0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2fe00 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2fe10 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2fe20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2fe30 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2fe40 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2fe50 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2fe60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2fe70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2fe80 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2fe90 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2fea0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2feb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2fec0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2fed0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2fee0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2fef0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2ff00 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2ff10 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2ff20 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2ff30 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2ff40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ff50 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2ff60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ff70 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2ff80 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2ff90 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2ffa0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2ffb0 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2ffc0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2ffd0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2ffe0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2fff0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
30000 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30010 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
30020 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
30030 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
30040 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
30050 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
30060 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
30070 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
30080 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30090 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
300a0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
300b0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
300c0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
300d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
300e0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
300f0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
30100 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30110 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
30120 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
30130 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
30140 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62  * <b>Warning:</b
30150 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  > ^The object re
30160 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
30170 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
30180 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
30190 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
301a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
301b0 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61   In a multithrea
301c0 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c  ded environment,
301d0 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  .** an unprotect
301e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
301f0 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79   object may only
30200 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20   be used safely 
30210 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
30220 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
30230 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
30240 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
30250 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
30260 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30270 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
30280 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
30290 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
302a0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
302b0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
302c0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
302d0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
302e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
302f0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
30300 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
30310 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
30320 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
30330 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f  e behavior is no
30340 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a  t threadsafe..**
30350 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
30360 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
30370 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
30380 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
30390 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
303a0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
303b0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
303c0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
303d0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
303e0 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
303f0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
30400 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
30410 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
30420 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
30430 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
30440 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
30450 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
30460 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
30470 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
30480 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
30490 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
304a0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
304b0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
304c0 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
304d0 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
304e0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
304f0 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
30500 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
30510 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
30520 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
30530 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
30540 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
30550 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
30560 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
30570 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
30580 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
30590 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
305a0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
305b0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
305c0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
305d0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
305e0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
305f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
30600 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
30610 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
30620 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
30630 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
30640 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
30650 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
30660 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
30670 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
30680 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
30690 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
306a0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
306b0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
306c0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
306d0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
306e0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
306f0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  R.** <tr><td>  F
30700 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
30710 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
30720 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
30730 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
30740 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
30750 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
30760 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a   [CAST] to BLOB.
30770 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
30780 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
30790 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
307a0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
307b0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
307c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
307d0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
307e0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
307f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
30800 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
30810 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
30820 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
30830 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
30840 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
30850 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
30860 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
30870 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
30880 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
30890 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
308a0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
308b0 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
308c0 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
308d0 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
308e0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
308f0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
30900 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
30910 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
30920 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
30930 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
30940 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
30950 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
30960 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30970 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
30980 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30990 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
309a0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
309b0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
309c0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
309d0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
309e0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
309f0 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
30a00 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
30a10 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
30a20 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
30a30 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
30a40 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
30a50 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
30a60 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
30a70 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
30a80 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
30a90 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
30aa0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
30ab0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
30ac0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
30ad0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
30ae0 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
30af0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30b00 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
30b10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30b20 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
30b30 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
30b40 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
30b50 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
30b60 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
30b70 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
30b80 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
30b90 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
30ba0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
30bb0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
30bc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
30bd0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
30be0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
30bf0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
30c00 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
30c10 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
30c20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
30c30 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
30c40 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
30c50 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
30c60 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
30c70 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
30c80 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
30c90 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
30ca0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
30cb0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
30cc0 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
30cd0 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
30ce0 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
30cf0 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
30d00 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
30d10 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
30d20 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
30d30 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
30d40 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
30d50 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
30d60 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
30d70 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
30d80 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
30d90 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
30da0 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73  safest policy is
30db0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
30dc0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
30dd0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
30de0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
30df0 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
30e00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30e10 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
30e20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30e30 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
30e40 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
30e50 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
30e60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
30e70 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
30e80 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
30e90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
30ea0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
30eb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30ec0 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
30ed0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
30ee0 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
30ef0 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
30f00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30f10 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
30f20 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
30f30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30f40 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
30f50 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
30f60 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
30f70 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
30f80 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
30f90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
30fa0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
30fb0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
30fc0 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
30fd0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
30fe0 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
30ff0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
31000 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
31010 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31020 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
31030 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
31040 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
31050 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
31060 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
31070 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
31080 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
31090 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
310a0 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
310b0 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
310c0 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
310d0 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
310e0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
310f0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
31100 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
31110 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31120 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
31130 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
31140 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
31150 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
31160 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
31170 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
31180 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
31190 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
311a0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d  tically.  Do <em
311b0 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74  >not</em> pass t
311c0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
311d0 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
311e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
311f0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
31200 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
31210 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
31220 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
31230 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
31240 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
31250 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
31260 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
31270 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
31280 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
31290 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
312a0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
312b0 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
312c0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
312d0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
312e0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
312f0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
31300 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
31310 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
31320 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
31330 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
31340 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
31350 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
31360 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
31370 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
31380 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31390 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
313a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
313b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
313c0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
313d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
313e0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
313f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
31400 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
31410 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
31420 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31430 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
31440 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
31450 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31460 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
31470 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
31480 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
31490 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
314a0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
314b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
314c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
314d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
314e0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
314f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31500 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
31510 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31520 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
31530 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
31540 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31550 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
31560 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31570 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
31580 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
315a0 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
315b0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
315c0 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43  bject.** DESTRUC
315d0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
315e0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
315f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
31600 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
31610 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
31620 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31630 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
31640 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
31650 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
31660 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
31670 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
31680 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
31690 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
316a0 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
316b0 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
316c0 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
316d0 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
316e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
316f0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
31700 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
31710 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
31720 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
31730 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
31740 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
31750 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
31760 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
31770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31780 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
31790 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
317a0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
317b0 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
317c0 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
317d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
317e0 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
317f0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
31800 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
31810 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
31820 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
31830 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
31840 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
31850 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
31860 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
31870 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
31880 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
31890 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
318a0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
318b0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
318c0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
318d0 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
318e0 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
318f0 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
31900 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
31910 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
31920 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
31930 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
31940 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
31950 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
31960 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
31970 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
31980 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
31990 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
319a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
319b0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
319c0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
319d0 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
319e0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
319f0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
31a00 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
31a10 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
31a20 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
31a30 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
31a40 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
31a50 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
31a60 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  ruption..*/.int 
31a70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31a80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
31a90 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
31aa0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
31ab0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
31ac0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54  nt Object.** MET
31ad0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
31ae0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
31af0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
31b00 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
31b10 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
31b20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
31b30 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
31b40 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
31b50 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
31b60 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
31b70 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
31b80 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
31b90 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
31ba0 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
31bb0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
31bc0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
31bd0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
31be0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
31bf0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
31c00 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
31c10 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
31c20 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
31c30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
31c40 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
31c50 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
31c60 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
31c70 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
31c80 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
31c90 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
31ca0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
31cb0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
31cc0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
31cd0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
31ce0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
31cf0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
31d00 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
31d10 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
31d20 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
31d30 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
31d40 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
31d50 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
31d60 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
31d70 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
31d80 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
31d90 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
31da0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
31db0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
31dc0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
31dd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31de0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
31df0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
31e00 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
31e10 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
31e20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
31e30 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
31e40 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
31e50 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
31e60 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
31e70 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
31e80 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
31e90 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
31ea0 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
31eb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31ec0 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
31ed0 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
31ee0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
31ef0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
31f00 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
31f10 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
31f20 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
31f30 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
31f40 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
31f50 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
31f60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
31f70 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
31f80 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
31f90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
31fa0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
31fb0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
31fc0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
31fd0 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
31fe0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
31ff0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
32000 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
32010 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
32020 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
32030 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
32040 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
32050 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
32060 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
32070 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
32080 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
32090 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a  rences between.*
320a0 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * these routines
320b0 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e   are the text en
320c0 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20  coding expected 
320d0 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  for.** the secon
320e0 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  d parameter (the
320f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e   name of the fun
32100 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61  ction being crea
32110 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ted).** and the 
32120 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65  presence or abse
32130 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63  nce of a destruc
32140 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  tor callback for
32150 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
32160 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
32170 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
32180 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
32190 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
321a0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
321b0 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
321c0 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
321d0 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
321e0 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
321f0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
32200 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
32210 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
32220 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
32230 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
32240 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
32250 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
32260 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
32270 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ely..**.** ^The 
32280 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
32290 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
322a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
322b0 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
322c0 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
322d0 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
322e0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
322f0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
32300 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72   in a UTF-8.** r
32310 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65  epresentation, e
32320 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
32330 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
32340 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65    ^Note that the
32350 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20   name.** length 
32360 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d  limit is in UTF-
32370 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61  8 bytes, not cha
32380 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d  racters nor UTF-
32390 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e  16 bytes.  .** ^
323a0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
323b0 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
323c0 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
323d0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
323e0 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  lt in [SQLITE_MI
323f0 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75  SUSE] being retu
32400 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
32410 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
32420 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
32430 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
32440 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
32450 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
32460 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
32470 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61  s. ^If this para
32480 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65  meter is -1, the
32490 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  n the SQL functi
324a0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
324b0 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20  te may take any 
324c0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
324d0 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e  nts between 0 an
324e0 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73  d the limit.** s
324f0 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  et by [sqlite3_l
32500 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
32510 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
32520 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  ]).  If the thir
32530 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
32540 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f  s less than -1 o
32550 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
32560 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  27 then the beha
32570 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
32580 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
32590 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
325a0 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
325b0 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
325c0 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
325d0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
325e0 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
325f0 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
32600 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54  s parameters.  T
32610 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
32620 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70  hould set this p
32630 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
32640 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
32650 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  if the function 
32660 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
32670 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69  nvokes .** [sqli
32680 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32690 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  le()] on an inpu
326a0 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  t, or [SQLITE_UT
326b0 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a  F16BE] if the.**
326c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
326d0 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33  invokes [sqlite3
326e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
326f0 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20  )] on an input, 
32700 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  or.** [SQLITE_UT
32710 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33  F16] if [sqlite3
32720 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
32730 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51   is used, or [SQ
32740 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74  LITE_UTF8].** ot
32750 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73  herwise.  ^The s
32760 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
32770 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
32780 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
32790 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65  s using.** diffe
327a0 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74  rent preferred t
327b0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77  ext encodings, w
327c0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d  ith different im
327d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
327e0 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69  r.** each encodi
327f0 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ng..** ^When mul
32800 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
32810 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
32820 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
32830 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
32840 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
32850 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
32860 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
32870 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
32880 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
32890 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
328a0 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61  eter may optiona
328b0 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68  lly be ORed with
328c0 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
328d0 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69  NISTIC].** to si
328e0 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75  gnal that the fu
328f0 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61  nction will alwa
32900 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
32910 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a  me result given.
32920 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  ** the same inpu
32930 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67  ts within a sing
32940 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
32950 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63  .  Most SQL func
32960 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74  tions are.** det
32970 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65  erministic.  The
32980 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f   built-in [rando
32990 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  m()] SQL functio
329a0 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  n is an example 
329b0 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  of a.** function
329c0 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74   that is not det
329d0 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65  erministic.  The
329e0 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c   SQLite query pl
329f0 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f  anner is able to
32a00 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69  .** perform addi
32a10 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74  tional optimizat
32a20 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e  ions on determin
32a30 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c  istic functions,
32a40 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68   so use.** of th
32a50 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  e [SQLITE_DETERM
32a60 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73  INISTIC] flag is
32a70 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65   recommended whe
32a80 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a  re possible..**.
32a90 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
32aa0 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
32ab0 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
32ac0 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
32ad0 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
32ae0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
32af0 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
32b00 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
32b10 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
32b20 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
32b30 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
32b40 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
32b50 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
32b60 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
32b70 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
32b80 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
32b90 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
32ba0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
32bb0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
32bc0 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
32bd0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
32be0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
32bf0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32c00 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
32c10 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
32c20 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
32c30 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
32c40 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
32c50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
32c60 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
32c70 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
32c80 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
32c90 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
32ca0 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
32cb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
32cc0 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
32cd0 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
32ce0 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
32cf0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
32d00 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
32d10 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  s NULL pointers 
32d20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
32d30 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
32d40 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
32d50 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
32d60 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
32d70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
32d80 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
32d90 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
32da0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
32db0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
32dc0 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
32dd0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
32de0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
32df0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
32e00 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
32e10 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
32e20 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
32e30 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
32e40 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
32e50 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
32e60 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
32e70 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
32e80 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
32e90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
32ea0 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
32eb0 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
32ec0 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
32ed0 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
32ee0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
32ef0 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
32f00 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
32f10 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
32f20 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
32f30 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
32f40 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
32f50 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
32f60 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
32f70 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
32f80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
32f90 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
32fa0 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
32fb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
32fc0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
32fd0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
32fe0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
32ff0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
33000 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
33010 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
33020 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
33030 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
33040 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
33050 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
33060 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
33070 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
33080 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
33090 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
330a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
330b0 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
330c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
330d0 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
330e0 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
330f0 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
33100 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
33110 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
33120 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
33130 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
33140 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
33150 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
33160 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
33170 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
33180 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
33190 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
331a0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
331b0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
331c0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
331d0 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
331e0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
331f0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
33200 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
33210 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
33220 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
33230 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
33240 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
33250 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
33260 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
33270 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
33280 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
33290 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
332a0 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
332b0 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
332c0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
332d0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
332e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
332f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
33300 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
33310 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
33320 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
33330 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
33340 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
33350 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
33360 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
33370 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
33380 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
33390 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
333a0 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
333b0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
333c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
333d0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
333e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
333f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
33400 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
33410 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
33420 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
33430 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
33440 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
33450 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
33460 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
33470 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
33480 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
33490 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
334a0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
334b0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
334c0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
334d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
334e0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
334f0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
33500 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
33510 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
33520 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
33530 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
33540 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
33550 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33560 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33570 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
33580 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
33590 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
335a0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
335b0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
335c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
335d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
335e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
335f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
33600 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33610 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
33620 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
33630 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
33640 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
33650 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
33660 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
33670 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
33680 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
33690 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
336a0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
336b0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
336c0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
336d0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
336e0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
336f0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
33700 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
33710 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
33720 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
33730 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
33740 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
33750 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
33760 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
33770 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
33780 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
33790 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
337a0 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20     1    /* IMP: 
337b0 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f  R-37514-35566 */
337c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
337d0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
337e0 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33      /* IMP: R-03
337f0 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65  371-37637 */.#de
33800 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
33810 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20  6BE        3    
33820 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d  /* IMP: R-51971-
33830 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65  34154 */.#define
33840 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
33850 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
33860 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
33870 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
33880 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
33890 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65        5    /* De
338a0 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66  precated */.#def
338b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
338c0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
338d0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
338e0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
338f0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
33900 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61  EF: Function Fla
33910 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
33920 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
33930 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69  ORed together wi
33940 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
33950 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72  TE_UTF8 | prefer
33960 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
33970 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  g] as the fourth
33980 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
33990 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
339a0 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  function()], [sq
339b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
339c0 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ction16()], or.*
339d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
339e0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d  e_function_v2()]
339f0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
33a00 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
33a10 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a  C    0x800../*.*
33a20 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
33a30 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
33a40 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
33a50 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
33a60 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
33a70 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
33a80 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
33a90 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
33aa0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
33ab0 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
33ac0 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
33ad0 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
33ae0 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
33af0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
33b00 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
33b10 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
33b20 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
33b30 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67  o encourage prog
33b40 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64  rammers to avoid
33b50 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
33b60 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74  ons, we will not
33b70 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68   explain what th
33b80 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
33b90 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
33ba0 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
33bb0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
33bc0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
33bd0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
33be0 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
33bf0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
33c00 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
33c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
33c20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
33c30 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  D int sqlite3_tr
33c40 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
33c50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
33c60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
33c70 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
33c80 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
33c90 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
33ca0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
33cb0 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
33cc0 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
33cd0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
33ce0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
33cf0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
33d00 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
33d10 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
33d20 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  nt),.           
33d30 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a             void*
33d40 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
33d50 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
33d60 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
33d70 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  ng SQL Values.**
33d80 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33d90 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65  _value.**.** The
33da0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
33db0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
33dc0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
33dd0 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
33de0 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
33df0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
33e00 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
33e10 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
33e20 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
33e30 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
33e40 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  .  .**.** The xF
33e50 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
33e60 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
33e70 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
33e80 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
33e90 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
33ea0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
33eb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
33ec0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
33ed0 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
33ee0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
33ef0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
33f00 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
33f10 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
33f20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
33f30 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
33f40 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
33f50 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
33f60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
33f70 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
33f80 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
33f90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33fa0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
33fb0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
33fc0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
33fd0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
33fe0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
33ff0 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
34000 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
34010 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
34020 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
34030 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
34040 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
34050 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34060 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
34070 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
34080 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
34090 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
340a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
340b0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
340c0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
340d0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
340e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
340f0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
34100 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
34110 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
34120 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
34130 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72  ept that these r
34140 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
34150 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
34160 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34170 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
34180 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
34190 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
341a0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
341b0 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
341c0 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
341d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
341e0 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
341f0 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
34200 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
34210 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
34220 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
34230 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
34240 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
34250 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
34260 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
34270 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
34280 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
34290 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
342a0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
342b0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
342c0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
342d0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
342e0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
342f0 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
34300 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
34310 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
34320 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
34330 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
34340 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
34350 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
34360 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
34370 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
34380 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
34390 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
343a0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
343b0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
343c0 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
343d0 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
343e0 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
343f0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
34400 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
34410 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
34420 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
34430 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
34440 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
34450 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
34460 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
34470 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
34480 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
34490 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
344a0 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
344b0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
344c0 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
344d0 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
344e0 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
344f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
34500 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
34510 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34520 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
34530 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34540 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
34550 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
34560 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
34570 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
34580 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
34590 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
345a0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
345b0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
345c0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
345d0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
345e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
345f0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
34600 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
34610 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
34620 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
34630 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
34640 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
34650 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
34660 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
34670 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
34680 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34690 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
346a0 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
346b0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
346c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
346d0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
346e0 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
346f0 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
34700 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34710 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
34720 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
34730 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
34740 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
34750 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
34760 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
34770 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
34780 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
34790 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
347a0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
347b0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
347c0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
347d0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
347e0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
347f0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
34800 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
34810 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
34820 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
34830 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
34840 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
34850 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
34860 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
34870 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
34880 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
34890 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
348a0 50 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67 20  PI3REF: Finding 
348b0 54 68 65 20 53 75 62 74 79 70 65 20 4f 66 20 53  The Subtype Of S
348c0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
348d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
348e0 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ue.**.** The sql
348f0 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79  ite3_value_subty
34900 70 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72  pe(V) function r
34910 65 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 79  eturns the subty
34920 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70  pe for.** an [ap
34930 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34940 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20  d SQL function] 
34950 61 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65  argument V.  The
34960 20 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f   subtype.** info
34970 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75  rmation can be u
34980 73 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69  sed to pass a li
34990 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  mited amount of 
349a0 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20  context from.** 
349b0 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  one SQL function
349c0 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73   to another.  Us
349d0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  e the [sqlite3_r
349e0 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d  esult_subtype()]
349f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73  .** routine to s
34a00 65 74 20 74 68 65 20 73 75 62 74 79 70 65 20 66  et the subtype f
34a10 6f 72 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  or the return va
34a20 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75  lue of an SQL fu
34a30 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  nction..**.** SQ
34a40 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73  Lite makes no us
34a50 65 20 6f 66 20 73 75 62 74 79 70 65 20 69 74 73  e of subtype its
34a60 65 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20  elf.  It merely 
34a70 70 61 73 73 65 73 20 74 68 65 20 73 75 62 74 79  passes the subty
34a80 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72  pe.** from the r
34a90 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70  esult of one [ap
34aa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34ab0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20  d SQL function] 
34ac0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75  into the.** inpu
34ad0 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f  t of another..*/
34ae0 0a 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 71  .unsigned int sq
34af0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74  lite3_value_subt
34b00 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
34b10 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
34b20 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46  3REF: Copy And F
34b30 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a  ree SQL Values.*
34b40 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34b50 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54  3_value.**.** ^T
34b60 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
34b70 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63  _dup(V) interfac
34b80 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
34b90 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
34ba0 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
34bb0 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  D and returns a 
34bc0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
34bd0 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c  copy.  ^The [sql
34be0 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75  ite3_value] retu
34bf0 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72  rned.** is a [pr
34c00 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
34c10 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76  value] object ev
34c20 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  en if the input 
34c30 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20  is not..** ^The 
34c40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
34c50 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 72  p(V) interface r
34c60 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56  eturns NULL if V
34c70 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61   is NULL or if a
34c80 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
34c90 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a  ation fails..**.
34ca0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34cb0 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e  value_free(V) in
34cc0 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61 6e  terface frees an
34cd0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34ce0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69   object.** previ
34cf0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
34d00 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
34d10 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20  ue_dup()].  ^If 
34d20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  V is a NULL poin
34d30 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  ter.** then sqli
34d40 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56  te3_value_free(V
34d50 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ) is a harmless 
34d60 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65  no-op..*/.sqlite
34d70 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
34d80 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74  _value_dup(const
34d90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
34da0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 76  ;.void sqlite3_v
34db0 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65  alue_free(sqlite
34dc0 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
34dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
34de0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
34df0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
34e00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34e10 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49  _context.**.** I
34e20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
34e30 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
34e40 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
34e50 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
34e60 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
34e70 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
34e80 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
34e90 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
34ea0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
34eb0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
34ec0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
34ed0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
34ee0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
34ef0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
34f00 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
34f10 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
34f20 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
34f30 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
34f40 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
34f50 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
34f60 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
34f70 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
34f80 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
34f90 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
34fa0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
34fb0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
34fc0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
34fd0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
34fe0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
34ff0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
35000 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
35010 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
35020 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
35030 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
35040 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
35050 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
35060 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
35070 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
35080 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
35090 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
350a0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
350b0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
350c0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
350d0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
350e0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
350f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
35100 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
35110 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
35120 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
35130 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
35140 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
35150 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
35160 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
35170 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
35180 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
35190 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
351a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
351b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
351c0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
351d0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
351e0 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
351f0 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
35200 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
35210 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
35220 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
35230 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
35240 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
35250 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
35260 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
35270 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
35280 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
35290 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
352a0 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
352b0 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
352c0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
352d0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
352e0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
352f0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
35300 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
35310 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
35320 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
35330 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
35340 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
35350 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
35360 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
35370 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
35380 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
35390 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
353a0 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
353b0 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
353c0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
353d0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
353e0 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
353f0 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
35400 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
35410 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
35420 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
35430 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
35440 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
35450 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
35460 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
35470 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
35480 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
35490 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
354a0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
354b0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
354c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
354d0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
354e0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
354f0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
35500 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
35510 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
35520 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
35530 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
35540 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
35550 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
35560 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
35570 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
35580 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
35590 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
355a0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
355b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
355c0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
355d0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
355e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
355f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
35600 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
35610 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
35620 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
35630 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
35640 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
35650 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35660 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
35670 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35680 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
35690 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
356a0 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
356b0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
356c0 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
356d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
356e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
356f0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
35700 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35710 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
35720 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
35730 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
35740 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35750 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35760 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
35770 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
35780 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
35790 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
357a0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
357b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
357c0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
357d0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
357e0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
357f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
35800 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35810 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
35820 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
35830 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
35840 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
35850 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35860 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
35870 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
35880 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
35890 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
358a0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
358b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
358c0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
358d0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
358e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
358f0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
35900 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35910 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
35920 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
35930 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
35940 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
35950 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
35960 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ion..*/.sqlite3 
35970 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
35980 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
35990 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
359a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
359b0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
359c0 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44  y Data.** METHOD
359d0 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
359e0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  t.**.** These fu
359f0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
35a00 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72  sed by (non-aggr
35a10 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74  egate) SQL funct
35a20 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
35a30 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
35a40 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
35a50 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
35a60 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
35a70 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
35a80 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
35a90 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
35aa0 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
35ab0 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
35ac0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
35ad0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
35ae0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
35af0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
35b00 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a  .  An example.**
35b10 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d   of where this m
35b20 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69  ight be useful i
35b30 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65  s in a regular-e
35b40 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
35b50 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ng.** function. 
35b60 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
35b70 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
35b80 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
35b90 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a  an be stored as.
35ba0 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
35bb0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
35bc0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20  pattern string. 
35bd0 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e   .** Then as lon
35be0 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e  g as the pattern
35bf0 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20   string remains 
35c00 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65  the same,.** the
35c10 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
35c20 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
35c30 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
35c40 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
35c50 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
35c60 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  e function..**.*
35c70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
35c80 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
35c90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
35ca0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
35cb0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
35cc0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
35cd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
35ce0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
35cf0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
35d00 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
35d10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
35d20 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
35d30 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
35d40 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
35d50 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
35d60 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
35d70 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33  nt, this sqlite3
35d80 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
35d90 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
35da0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
35db0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
35dc0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35dd0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65  ta(C,N,P,X) inte
35de0 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73  rface saves P as
35df0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
35e00 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
35e10 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
35e20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35e30 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71  nction.  ^Subseq
35e40 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
35e50 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
35e60 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e  data(C,N) return
35e70 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74   P from the most
35e80 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74   recent.** sqlit
35e90 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
35ea0 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20  ,N,P,X) call if 
35eb0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
35ec0 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a  still valid or.*
35ed0 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65  * NULL if the me
35ee0 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
35ef0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41  discarded..** ^A
35f00 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74  fter each call t
35f10 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
35f20 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77  xdata(C,N,P,X) w
35f30 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55  here X is not NU
35f40 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  LL,.** SQLite wi
35f50 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
35f60 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
35f70 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74  n X with paramet
35f80 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20  er P exactly.** 
35f90 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d  once, when the m
35fa0 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61  etadata is disca
35fb0 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  rded..** SQLite 
35fc0 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61  is free to disca
35fd0 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  rd the metadata 
35fe0 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63  at any time, inc
35ff0 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20  luding: <ul>.** 
36000 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f  <li> when the co
36010 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
36020 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
36030 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c  hanges, or.** <l
36040 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  i> when [sqlite3
36050 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
36060 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
36070 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  ] is called for 
36080 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20  the.**      SQL 
36090 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a  statement, or.**
360a0 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74   <li> when sqlit
360b0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
360c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69   is invoked agai
360d0 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61  n on the same pa
360e0 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c  rameter, or.** <
360f0 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f  li> during the o
36100 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f  riginal sqlite3_
36110 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61  set_auxdata() ca
36120 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79  ll when a memory
36130 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61   .**      alloca
36140 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
36150 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  s. </ul>)^.**.**
36160 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62   Note the last b
36170 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75  ullet in particu
36180 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75  lar.  The destru
36190 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71  ctor X in .** sq
361a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
361b0 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74  a(C,N,P,X) might
361c0 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64   be called immed
361d0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74  iately, before t
361e0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  he.** sqlite3_se
361f0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
36200 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72  rface even retur
36210 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74  ns.  Hence sqlit
36220 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
36230 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61  .** should be ca
36240 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e  lled near the en
36250 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  d of the functio
36260 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
36270 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63   and the.** func
36280 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
36290 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d  ion should not m
362a0 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50  ake any use of P
362b0 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65   after.** sqlite
362c0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
362d0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  has been called.
362e0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
362f0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
36300 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
36310 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
36320 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ls for.** functi
36330 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  on parameters th
36340 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74  at are compile-t
36350 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69  ime constants, i
36360 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c  ncluding literal
36370 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
36380 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20  parameters] and 
36390 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70  expressions comp
363a0 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  osed from the sa
363b0 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  me.)^.**.** Thes
363c0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
363d0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
363e0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
363f0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
36400 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
36410 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
36420 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
36430 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
36440 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
36450 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
36460 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
36470 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
36480 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
36490 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
364a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
364b0 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
364c0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
364d0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
364e0 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
364f0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
36500 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
36510 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
36520 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
36530 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
36540 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
36550 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
36560 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
36570 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
36580 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
36590 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
365a0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
365b0 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
365c0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
365d0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
365e0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
365f0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
36600 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
36610 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
36620 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
36630 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
36640 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
36650 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
36660 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
36670 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
36680 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
36690 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
366a0 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
366b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
366c0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
366d0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
366e0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
366f0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
36700 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64  pilers..*/.typed
36710 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
36720 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
36730 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
36740 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
36750 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
36760 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
36770 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
36780 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
36790 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
367a0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
367b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
367c0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
367d0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
367e0 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  on.** METHOD: sq
367f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
36800 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
36810 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
36820 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
36830 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
36840 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
36850 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
36860 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
36870 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
36880 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36890 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
368a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
368b0 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
368c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
368d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
368e0 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
368f0 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
36900 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
36910 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
36920 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
36930 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
36940 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
36950 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
36960 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
36970 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
36980 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
36990 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
369a0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
369b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
369c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
369d0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
369e0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
369f0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
36a00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36a10 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
36a20 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
36a30 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
36a40 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
36a50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
36a60 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
36a70 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
36a80 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
36a90 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
36aa0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36ab0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e  ult_zeroblob(C,N
36ac0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
36ad0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  sult_zeroblob64(
36ae0 43 2c 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  C,N).** interfac
36af0 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
36b00 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
36b10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36b20 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
36b30 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
36b40 20 61 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73 20   all zero bytes 
36b50 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
36b60 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ize..**.** ^The 
36b70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
36b80 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
36b90 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
36ba0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
36bb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36bc0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36bd0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
36be0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
36bf0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
36c00 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
36c10 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36c20 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
36c30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36c40 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
36c50 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
36c60 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
36c70 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
36c80 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
36c90 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
36ca0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
36cb0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
36cc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
36cd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36ce0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
36cf0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36d00 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
36d10 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
36d20 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
36d30 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
36d40 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
36d50 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
36d60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36d70 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
36d80 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
36d90 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
36da0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
36db0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
36dc0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
36dd0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
36de0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
36df0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
36e00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36e10 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
36e20 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
36e30 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
36e40 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
36e50 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
36e60 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
36e70 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
36e80 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
36e90 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
36ea0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
36eb0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
36ec0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
36ed0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36ee0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
36ef0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
36f00 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
36f10 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
36f20 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
36f30 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
36f40 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
36f50 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
36f60 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36f70 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
36f80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36f90 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
36fa0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
36fb0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
36fc0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
36fd0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
36fe0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
36ff0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
37000 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
37010 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
37020 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
37030 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
37040 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
37050 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37060 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
37070 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
37080 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
37090 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
370a0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
370b0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
370c0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
370d0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
370e0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
370f0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
37100 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
37110 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
37120 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
37130 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37140 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
37150 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
37160 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
37170 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37180 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37190 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
371a0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
371b0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
371c0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
371d0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
371e0 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
371f0 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
37200 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37210 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37220 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
37230 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
37240 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
37250 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
37260 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
37270 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
37280 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
37290 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
372a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
372b0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
372c0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
372d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
372e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
372f0 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
37300 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
37310 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
37320 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
37330 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
37340 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
37350 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
37360 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
37370 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
37380 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
37390 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
373a0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
373b0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
373c0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
373d0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
373e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
373f0 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
37400 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
37410 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
37420 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37430 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37440 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
37450 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37460 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
37470 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37480 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
37490 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
374a0 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
374b0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
374c0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
374d0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
374e0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
374f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37500 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
37510 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
37520 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
37530 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
37540 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
37550 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
37560 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
37570 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
37580 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
37590 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73  ively..** ^The s
375a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
375b0 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  xt64() interface
375c0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
375d0 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20   value of an.** 
375e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
375f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
37600 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  be a text string
37610 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a   in an encoding.
37620 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ** specified by 
37630 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c  the fifth (and l
37640 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20  ast) parameter, 
37650 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e  which must be on
37660 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f  e.** of [SQLITE_
37670 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
37680 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
37690 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
376a0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a  ITE_UTF16LE]..**
376b0 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
376c0 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
376d0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
376e0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
376f0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
37700 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
37710 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
37720 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
37730 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
37740 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
37750 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
37760 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
37770 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
37780 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
37790 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
377a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
377b0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
377c0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
377d0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
377e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
377f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37800 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
37810 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
37820 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
37830 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
37840 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
37850 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
37860 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
37870 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
37880 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
37890 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
378a0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20  unction result. 
378b0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
378c0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67  meter is non-neg
378d0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a  ative, then it.*
378e0 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  * must be the by
378f0 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74  te offset into t
37900 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
37910 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
37920 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65  or would.** appe
37930 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ar if the string
37940 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69   where NUL termi
37950 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
37960 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
37970 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74  cur.** in the st
37980 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f  ring at a byte o
37990 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65  ffset that is le
379a0 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75  ss than the valu
379b0 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20  e of the 3rd.** 
379c0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
379d0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
379e0 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69  ring will contai
379f0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  n embedded NULs 
37a00 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  and the.** resul
37a10 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
37a20 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74   operating on st
37a30 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64  rings with embed
37a40 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
37a50 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  fined..** ^If th
37a60 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
37a70 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
37a80 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
37a90 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
37aa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
37ab0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
37ac0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
37ad0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
37ae0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
37af0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
37b00 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
37b10 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
37b20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
37b30 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
37b40 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
37b50 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
37b60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37b70 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
37b80 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
37b90 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
37ba0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
37bb0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
37bc0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
37bd0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
37be0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
37bf0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
37c00 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
37c10 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
37c20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
37c30 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
37c40 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
37c50 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
37c60 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
37c70 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
37c80 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
37c90 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
37ca0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37cb0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37cc0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
37cd0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
37ce0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
37cf0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
37d00 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
37d10 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
37d20 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
37d30 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
37d40 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
37d50 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
37d60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
37d70 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
37d80 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
37d90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37da0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
37db0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
37dc0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
37dd0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37de0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
37df0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
37e00 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
37e10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
37e20 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
37e30 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
37e40 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
37e50 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
37e60 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
37e70 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
37e80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
37e90 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
37ea0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
37eb0 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
37ec0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
37ed0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
37ee0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
37ef0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37f00 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
37f10 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
37f20 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
37f30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37f40 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
37f50 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
37f60 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
37f70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
37f80 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
37f90 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
37fa0 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
37fb0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
37fc0 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
37fd0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
37fe0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
37ff0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
38000 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
38010 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
38020 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
38030 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
38040 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
38050 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
38060 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
38070 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
38080 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
38090 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
380a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76   undefined..*/.v
380b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
380c0 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
380d0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
380e0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
380f0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
38100 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
38110 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
38120 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76  context*,const v
38130 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  oid*,.          
38140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38150 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
38160 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
38170 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
38180 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
38190 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
381a0 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
381b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
381c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
381d0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
381e0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
381f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
38200 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
38210 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
38220 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
38230 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
38240 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
38250 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
38260 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
38270 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
38280 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
38290 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
382a0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
382b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
382c0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
382d0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
382e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
382f0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
38300 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
38310 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
38320 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
38330 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
38340 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
38350 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
38360 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
38370 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
38380 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
38390 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
383a0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
383b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
383c0 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  ext64(sqlite3_co
383d0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
383e0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
383f0 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
38400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
38410 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
38420 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
38430 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c  oding);.void sql
38440 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
38450 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
38460 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
38470 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
38480 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
38490 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
384a0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
384b0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
384c0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
384d0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
384e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
384f0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
38500 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
38510 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
38520 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
38530 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
38540 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
38550 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
38560 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
38570 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
38580 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
38590 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e  ext*, int n);.in
385a0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  t sqlite3_result
385b0 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69  _zeroblob64(sqli
385c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
385d0 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 6e 29 3b  lite3_uint64 n);
385e0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
385f0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 53  F: Setting The S
38600 75 62 74 79 70 65 20 4f 66 20 41 6e 20 53 51 4c  ubtype Of An SQL
38610 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54   Function.** MET
38620 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
38630 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  text.**.** The s
38640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75  qlite3_result_su
38650 62 74 79 70 65 28 43 2c 54 29 20 66 75 6e 63 74  btype(C,T) funct
38660 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 73  ion causes the s
38670 75 62 74 79 70 65 20 6f 66 0a 2a 2a 20 74 68 65  ubtype of.** the
38680 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
38690 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
386a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
386b0 6f 6e 5d 20 77 69 74 68 20 0a 2a 2a 20 5b 73 71  on] with .** [sq
386c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43  lite3_context] C
386d0 20 74 6f 20 62 65 20 74 68 65 20 76 61 6c 75 65   to be the value
386e0 20 54 2e 20 20 4f 6e 6c 79 20 74 68 65 20 6c 6f   T.  Only the lo
386f0 77 65 72 20 38 20 62 69 74 73 20 0a 2a 2a 20 6f  wer 8 bits .** o
38700 66 20 74 68 65 20 73 75 62 74 79 70 65 20 54 20  f the subtype T 
38710 61 72 65 20 70 72 65 73 65 72 76 65 64 20 69 6e  are preserved in
38720 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
38730 73 20 6f 66 20 53 51 4c 69 74 65 3b 0a 2a 2a 20  s of SQLite;.** 
38740 68 69 67 68 65 72 20 6f 72 64 65 72 20 62 69 74  higher order bit
38750 73 20 61 72 65 20 64 69 73 63 61 72 64 65 64 2e  s are discarded.
38760 0a 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  .** The number o
38770 66 20 73 75 62 74 79 70 65 20 62 79 74 65 73 20  f subtype bytes 
38780 70 72 65 73 65 72 76 65 64 20 62 79 20 53 51 4c  preserved by SQL
38790 69 74 65 20 6d 69 67 68 74 20 69 6e 63 72 65 61  ite might increa
387a0 73 65 0a 2a 2a 20 69 6e 20 66 75 74 75 72 65 20  se.** in future 
387b0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
387c0 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  te..*/.void sqli
387d0 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79  te3_result_subty
387e0 70 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  pe(sqlite3_conte
387f0 78 74 2a 2c 75 6e 73 69 67 6e 65 64 20 69 6e 74  xt*,unsigned int
38800 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33